This directory includes the supplementary artefact for the paper Iris-Wasm: Robust and Modular Verification of WebAssembly Programs, a submission to the 44th ACM SIGPLAN Symposium on Programming Language Design and Implementation (PLDI 2023).
The project comes with a pre-compiled VirtualBox VM image of the latest version (7.0.6).
The latest version of VirtualBox is available at https://www.virtualbox.org/wiki/Downloads.
The VM image is set up with the following credentials:
username: artefact
password: pldi2023_34
The artefact to be evaluated sits under home/Iris-Wasm-artefact/.
The artefact in the VM has been precompiled, with Emacs and Proof General already installed, so that proofs can be browsed and played around directly. The project comes with esy packaging: type esy shell to open a shell with the right compilation environment. For example:
esy emacs theories/iris/examples/iris_examples.v
This opens the file containing some direct examples of using the program logic in Emacs. Other proofs can be browsed similarly.
Note that emacs theories/iris/examples/iris_examples.v (without the esy prefix) will open Emacs outside the esy packaging environment, without setting the local dependencies correctly. Doing so will prevent coq from finding the necessary dependencies.
For some basic testing, the key stack example described in the paper resides in theories/iris/examples/stack/, with each of its module function implemented and verified in an individual file under theories/iris/examples/stack/function/. We invite the reviewers to run through the code and the fully-proved specifications of each function, which are omitted in the paper due to space constraint. The stack module stack_module itself is implemented and verified in theories/iris/examples/stack/stack_instantiation.v, importing its module functions.
To check against the line of code (LOC) table given in Fig. 4 (Line 736) of the paper, run make loc which will prints out a tally of LOC as given by the cloc command for each subdirectory under theories/iris/. Note that the examples folder contains both the examples and stack entry in the table, which is the correct sum (11541 = 2754 + 8787). This command uses cloc, which can be installed via:
apt install cloc
As a demonstration of reproducibility and reusability, we also welcome the reviewer to verify a manual compilation of the project from its source. The project comes with an esy packaging for easier dependency management and better reproducibility.
The following programs are required to be installed: git, curl, m4, autoconf, and automake. These programs are used to fetch and compile dependencies.
Installing esy itself can be done through npm.
We provide a list of commands to install all the aforementioned dependencies:
apt install npm git curl m4 autoconf
npm install --global esy@0.6.12 # Tested with version 0.6.12 of esy.
Once esy is installed, simply type esy to download and install the dependencies and compile everything.
esy
Compiling the development require at least 8GB of RAM and may take around 60 minutes.
For manual installations, once the artefact has been compiled, type esy shell to open a shell with the right compilation environment. For example:
esy emacs theories/iris/examples/iris_examples.v
This opens the file containing some direct examples of using the program logic in Emacs, assuming Emacs and Proof General are installed. Other proofs can be browsed similarly. Emacs can be installed via command line:
apt install emacs
The instruction to install Proof General can be found at https://proofgeneral.github.io.
Although not necessary, we also recommend installing the Company-Coq plugin for pretty printing and easier editing to the proofs. The instruction to install Company-Coq can be found at https://github.com/cpitclaudel/company-coq. Company-Coq is pre-installed in the VM image provided.
For manual installation, note that the Makefile under the repository is only intended to be used by the esy packaging to compile the Coq files in its environment after dependencies have been installed. A direct make will attempt to compile the Coq files outside the esy sandbox environment without fetching the correct dependencies and will likely fail. Instead, follow the manual installation guide above and execute esy in the end which performs the entire installation and compilation process.
If an existing version of esy is used but the manual installation fails, ensure that the version of esy being used is at least 0.6.12.
If there is a need to relocate files between folders for some reason, note that a direct esy for recompilation might be assuming the old file structure and fail to link the new paths. In that case, run esy clean first to clean up (this will not uninstall the dependencies, so a recompilation will not take as long as the fresh compilation did), then run esy again.
When browsing the proofs in Emacs + Proof General, a warning on boolean coercion will pop up in the Coq response prompt when the theorem prover runs past the imports. This is because two of our dependencies, ssreflect and stdpp, each implements its own coercion of Bool into Prop, resulting in ambiguous coercion paths. However, this can be safely ignored since the two implementations are essentially the same.
This artefact is a fully-verified implementation in Coq of the program logic proposed in the paper supporting all claims of the paper. Some simplification has been made in the presentation of the paper for space constraints, and we have tried our best to highlight all such differences in the section Differences with Paper in the end.
As a demonstration, executing Print Assumptions instantiate_stack_adv_spec at the end of the file iris/examples/stack/stack_module_robust.v (an example very deep in the codebase) shows that the theorem only relies on the the following logical axioms:
Axioms:
ClassicalDedekindReals.sig_not_dec : ∀ P : Prop, {¬ ¬ P} + {¬ P}
ClassicalDedekindReals.sig_forall_dec
: ∀ P : nat → Prop,
(∀ n : nat, {P n} + {¬ P n}) → {n : nat | ¬ P n} + {∀ n : nat, P n}
FunctionalExtensionality.functional_extensionality_dep
: ∀ (A : Type) (B : A → Type) (f g : ∀ x : A, B x),
(∀ x : A, f x = g x) → f = g
Eqdep.Eq_rect_eq.eq_rect_eq
: ∀ (U : Type) (p : U) (Q : U → Type) (x : Q p) (h : p = p),
x = eq_rect p Q x p h
Classical_Prop.classic : ∀ P : Prop, P ∨ ¬ P
We invite the reviewer to compare the key claims made in the paper against the code for a demonstration of completeness. We suggest starting from the stack example, which is the main running example in the paper, and then the other examples and the implementation of the program logic itself if interested. The detailed locations and an outline of them can be found under the Structure section below.
The remaining part of this readme aims to explain the structure of the artefact, and provide directories and paths to locate the items that have appeared in the paper.
For each figure, theorem, or files in the paper, we provide the rough paths, under theories/, to indicate where the relevant files are located. We also provide a general pointer for each subsection in Section 2 and Section 3 for the related files in the codebase. For a detailed breakdown of the code structure, see the Structure section later.
| Location in Paper | Location in Code |
|---|---|
| Fig. 1 | iris/examples/stack/ |
| Fig. 2 | datatypes.v |
| Section 2.1 | iris/language/iris.v, iris/rules/iris_rules_pure.v |
| Section 2.2 | iris/rules/, iris/examples/stack/function/push.v |
| Section 2.3 | iris/rules/, iris/examples/stack/function/stack_map.v |
| Section 3 | iris/host/, iris/instantiation/, iris/examples/stack/ |
| Fig. 3 | iris/iris_host.v |
| Fig. 5 | iris/examples/stack/stack_robust.v |
| Section 5 | iris/logrel/, iris/examples/stack/ |
| Theorem 5.1 | iris/examples/stack/stack_instantiation_interp.v |
| Theorem 5.2 | iris/examples/stack/stack_robust.v |
| Theorem 5.3 | iris/examples/stack/stack_module_robust.v |
In this section, we describe the structure of the implementation.
Our work uses the mechanisation of WebAssembly 1.0 by Watt et al. in Two Mechanisations of WebAssembly, FM21. As a result, our work inherits many files from Watt et al's mechanisised proofs. These files are located directly under theories and are not claimed as part of contributions of this paper. We bring up the files most related to our work for completeness:
datatypes.v contains all the basic WebAssembly data types definitions;
opsem.v defines the operational semantics of WebAssembly;
typing.v defines the type system for WebAssembly instructions, closures, and stores, and configurations.
instantiation.v contains the definition of the module instantiation predicate in the official specification, as well as all the sub-predicates it depends on.
We chose to leave most parts of these files intact, except for our only slight reformulation of the host function implementation by adding the AI_call_host administrative instruction (as discussed in the paper), which caused some slight adaptations.
Our contribution in this work resides almost entirely under theories/iris.
Under theories/iris/language, we fit WebAssembly language into the Iris Language framework, prepare the preambles for our program logic and logical relation.
iris.v: fits WebAssembly into an Iris Language by defining the logical values, expressions, and proving the necessary properties for them etc.;
iris_locations.v: sets up the necessary details to express and manipulate the memory model of the language;
iris_wp.v, iris_wp_def.v: sets up a custom weakest precondition to be used for our language, which differs slightly from the standard construct that Iris provides; defines the memory model of the language;
iris_adequacy.v: contains a proof to the adequacy of our weakest precondition;
iris_atomicity.v: contains a definition of which expressions are considered atmomic in Iris, and proves the definition is sound.
Under theories/iris/helpers, we established a lot of auxiliary properties about either the WebAssembly Semantics itself, or the plugging-in version of the semantics in Iris.
Under theories/iris/rules, we proved a vast number of proof rules that can be used to reason about WebAssembly programs. We have categorised the proof rules into a few files, according to their nature:
theories/iris/rules/iris_rules_pure.v: contains proof rules for pure instructions, i.e. those whose reduction semantics are independent from the state (for example, the wp_binop rule in Line 260);
theories/iris/rules/iris_rules_control.v: contains proof rules for control instructions;
theories/iris/rules/iris_rules_resources.v: contains proof rules that directly access the state, such as memory instructions;
theories/iris/rules/iris_rules_call.v: contains proof rules related to function calls;
theories/iris/rules/iris_rules_structural.v: contains structural proof rules to deal with sequencing of instruction sequences, possibly within evaluation contexts;
theories/iris/rules/iris_rules_trap.v: contains structural proof rules that allow reasoning when a part of the expression produce traps.
theories/iris/rules/iris_rules_bind.v: contains several bind rules for binding into evaluation contexts;
theories/iris/rules/iris_rules.v: imports everything above, allowing users to import all proof rules at the same time more easily.
Under theories/iris/instantiation, we build up the module instantiation resource update lemma (Lemma 2.1), which is later imported to establish the instantiation proof rule in our host language.
Under theories/iris/host, we build our host language introduced in Section 2.4 and establish a set of proof rules for the host language required for reasoning about our examples.
Under theories/iris/logrel/, we build a logical relation on top of the program logic we've established.
iris_logrel.v: contains the definition of all logical relations, starting from the simple relations for values and building up to sophisticated relations for module instances and expressions, contains the semantic typing definitions, and a generalised host integration record that defines the minimal requirements on a host program logic (note that it does not define restrictions on the host language itself, just the program logic). This file is the base of the logical relation.
iris_fundamental_(xxx).v: each of these files contains the proof to a case of the Fundamental Theorem for one single instruction.
iris_fundamental.v: imports all the case files above and derive the Fundamental Theorem (Theorem 3.2) in the paper, and its corollaries.
iris_interp_instance_alloc.v: proves the module instantiation allocates the correct Iris invariants as expected, which is used for the robust safety examples later.
Under theories/iris/examples/, we formulated the examples for our project, some of which were discussed in the paper. We bring up the key files below:
iris_examples.v: contains several simpler preliminary examples to help understand the program logic without involving modules and the host language.
iris_examples_factorial.v: contains the Landin's Knot example, where a factorial is implemented through store recursion.
stack/function/(function_name).v: provides the body of the functions declared in the stack module, proves a specification for them within our program logic, and proves the validity result for some of the functions;
stack/stack_instantiation.v: defines the stack module and proves its instantiation specification.
stack/stack_client.v: defines a client module that can use imports from the stack module and proves its instantiation specification.
stack/stack_common.v: includes some useful definitions and properties that are shared across the stack example.
stack/stack_with_reentrancy.v: defines a more sophisticated client module that features a reentrant host call to demonstrate interoperation between the WebAssembly the the host weakest precondition.
stack/stack_robust.v: defines yet another client module that imports an unknown module in addition to the stack module, and demonstrates the encapsulation property that can be obtained (discussed in Section 5).
stack/stack_module_robust.v: similar to the above, but no known client is defined; instead an adverserial module imports the stack module. The stack invariant can still be preserved nevertheless.
The following are other examples that were not discussed in the paper.
iris_robust_examples.v: a simpler robust safety example, containing an example host program which instantiates an adversary module followed by a trusted module. The trusted module calls an imported function from the unknown adversary module. We then demonstrate the robust safety property, where we have local state encapsulation in the presence of unknown code.
iris_robust_example_host.v: contains a variation of the above example, in which the adversary module imports a host function. The example demonstrates the integration between the logical relation and the host language.
iris_robust_examples_adequacy.v: applies adequacy on the above example.
The definitions within our work were designed in a way that would fit best in an interactive proof environment, to facilitate sustainable engineering in the long term. Therefore, some definitions, especially the constructors of inductive and records, are either named or designed in a verbose way.
There are two major categories of differences:
In the code, we exercise a naming convention for most constructors of inductive definitions and record by adding prefixes to them, so that it is possible to deduce the source of these constructors by looking at the prefix. Oftentimes these prefixes are in acronyms of the source definition (for example, BI_ for each constructor of basic instructions).
The large records in WebAssembly often involve fields of the same type (for example, in the instance definition, the addresses of functions, tables, memories, and globals are all immediate (isomorphic to naturals). In the code, we sometimes add another layer of constructor for each of them when unintended uses are possible (for example, looking up in tables by using a memory export reference).
We provide a list of other name differences in names below:
| References in Paper | Definition in Code |
|---|---|
| Fig. 2, Instruction | datatypes.v: basic_instruction |
| Line 248, Logical value | iris/iris.v: val |
| Fig. 3, import variable store | iris/iris_host.v: vi_store |
| Fig. 3, declaration | iris/iris_host.v: host_e |
Fig. 3, inst_decl |
iris/iris_host.v: ID_instantiate |
Line 410, wp_local_bind |
iris/rules/iris_rules_bind.v: wp_frame_bind |
| Location in Paper | Name in Paper | Definition in Code |
|---|---|---|
| Page 6 | Logical values | iris/language/iris.v, val |
| Page 15 | stateInterp | iris/language/iris_wp_def.v, gen_heap_wasm_store |
| Page 15 | resourcesImports | iris/host/iris_instantiation.v, instantiation_resources_pre_wasm |
| Page 15 | resources | iris/host/iris_instantiation.v, module_inst_resources_wasm and instantiation_resources_post_wasm |
WP rules and frame resource : the frame resource is occasionally put under a magic wand rather than in postcondition; the two presentations are equivalent in use.
wp_ctx_bind (Line 327 in paper, iris/rules/iris_rules_bind.v in code) : the bind rule presented in the paper is intended for evaluation contexts with at least one label, and it is thus required that es constitutes the full base layer in lh[es] (i.e. that lh has an empty base layer). Similar structural rules for sequencing have also been proved.
wp_local_bind (Line 410 in paper, wp_frame_bind in iris/rules/iris_rules_bind.v in code) : the local bind rule requires the inner body es to be reducible (if es were already a value, the bind is not necessary anyway, as the entire expression is already a logical value).
inst_decl (Line 591 in paper, ID_instantiate in code) : the order of arguments are reversed compared to the paper; in Coq it goes ID_instantiate exports modules imports which follows a style closer to the JS-Wasm API.