Skip to content

Releases: GaloisInc/saw-script

v1.2

03 Sep 16:20
Compare
Choose a tag to compare

New Features

  • Add mir_str_slice_value and mir_str_slice_range_value functions, which
    allow taking &str slices. For more information, see the documentation in the
    SAW manual.

  • Add mir_mux_values command for muxing two MIR values.

  • Add support for GHC 9.8.

Bug fixes

  • Fix bug that caused MIR to incorrectly reject overrides with multiple const slice arguments

  • Error messages have been improved such that the locations printed with type errors and other diagnostics now have a much stronger connection with reality.

v1.1

06 Feb 11:37
Compare
Choose a tag to compare

New Features

  • SAW now supports loading and reasoning about Cryptol declarations that make use of numeric constraint guards. For more information on numeric constraint guards, see the relavent section of the Cryptol reference manual.

  • Add an experimental mir_verify command, along with related utilities for constructing specifications for MIR/Rust programs. For more information, see the mir_* commands documented in the SAW manual.

  • SAW now supports importing Cryptol modules containing foreign declarations. For more information, see the manual.

  • Building on the above feature, SAW now supports automatically generating LLVM setup scripts for Cryptol FFI functions with the llvm_ffi_setup command. For more information, see the manual.

  • Ghost state is now supported with the JVM and MIR language backends:

    • The llvm_declare_ghost_state command is now deprecated in favor of the new declare_ghost_state command, as nothing about this command is LLVM-specific.
    • Add jvm_ghost_value and mir_ghost_value commands in addition to the existing llvm_ghost_value command.
  • SAW now includes an experimental set_solver_cache_path command, which caches the results of tactics which call out to automated provers. This can save a considerable amount of time when repeatedly running proof scripts. For more information, see the manual.

  • Add experimental support for verifying hardware circuits via VHDL and Yosys. There is now a family of experimental yosys_* commands that support this. For more information, see the manual.

  • Extend llvm_verify_x86 in order to handle x86 functions that spill arguments to the stack.

Bug fixes

v1.0

27 Jun 14:07
Compare
Choose a tag to compare

New Features

  • SAW now implements Heapster, which allows extracting functional specifications of memory-safe C programs to Coq. There is now a family of experimental heapster_* commands that support this. For more information, refer to the Heapster README.

  • New commands enable_what4_eval and disable_what4_eval to enable or disable What4 translation for SAWCore expressions during Crucible symbolic execution.

  • New command llvm_alloc_sym_init like llvm_alloc, but assume that the allocation is initialized with symbolic bytes. New commands disable_alloc_sym_init_check and enable_alloc_sym_init_check to disable or enable the allocation initialization check associated with llvm_alloc_sym_init during override application.

  • New command set_crucible_timeout to set the timeout for the SMT solver during the LLVM and X86 Crucible symbolic execution. This is used for path-sat checks, and sat checks when applying overrides.

  • New command w4_unint_z3_using like w4_unint_z3, but use the given Z3 tactic.

  • A new llvm_points_to_bitfield command has been introduced, providing a version of llvm_points_to that is specifically tailored for structs containing bitfields. In order to use llvm_points_to_bitfield, one must also use the new enable_lax_loads_and_stores command, which relaxes some of Crucible's assumptions about reading from uninitialized memory. (This command also comes with a corresponding disable_lax_loads_and_stores command.) For more details on how each of these commands should be used, consult the "Bitfields" section of the SAW manual.

  • A new llvm_cast_pointer function has been added that allows users to directly specify that a pointer should be treated as pointing to a particular type. This mainly affects the results of subsequent llvm_field and llvm_elem calls. This is especially useful for dealing with C union types, as the type information provided by LLVM is imprecise in these cases.

  • A new llvm_union function has been added that uses debug information to allow users to select fields from union types by name. This automates the process of manually applying llvm_cast_pointer with the type of the selected union field. Just as with llvm_field, debug symbols are required for llvm_union to work correctly.

  • A new highly experimental llvm_verify_fixpoint_x86 function that allows partial correctness verification of loops using loop invariants instead of full symbolic unrolling. Only certain very simple styles of loops can currently be accommodated, and the user is required to provide a term that describes how the live variables in the loop evolve over an iteration.

  • A new experimental facility for "tagging" proof obligations in specifications and later using those tags to make decisions in proof tactics. See the new llvm_setup_with_tag, goal_has_tags, and goal_has_some_tag commands.

  • A new experimental option (toggled via enable_single_override_special_case and disable_single_override_special_case) which changes the handling for cases where an overriden function has only one override that could possibly apply. When the special case handling is enabled, preconditions for the override are asserted separately, maintaining their individual metadata instead of being combined into a single precondition for the entire override. This may be advantageous if proving the individual goals is easier than the conjunction of all of them, or if different tactics are needed for different subgoals. Currently, this option only applies to LLVM verifications.

  • Experimental interactive features. Using the new subshell and proof_subshell commands, a user can regain a command-line interface in the middle of a running script for experimentation and exploration purposes. In addition callcc and checkpoint allow the user to have more flexibility with restoring prior states and executing the remaining context of a proof in such an interactive session.

  • A new experimental llvm_verify_x86_with_invariant command that allows verification certain kinds of simple loops by using a user-provided loop invariant.

  • Add a cvc5 family of proof scripts that use the CVC5 SMT solver. (Note that the sbv_cvc5 and sbv_unint_cvc5 are non-functional on Windows at this time due to a downstream issue with CVC5 1.0.4 and earlier.)

  • Add experimental support for verifying Rust programs. For more information, see the mir_* commands documented in the SAW manual.

Changes

  • A significant overhaul of the SAW proof and tactics system. Under the hood, tactics now manipulate sequents instead of just propositions. This allows more the user to specify more precise goal rearrangements, and provides a much nicer interface for proof exploration (especially with the new proof_subshell). There are a variety of new tactics that provide the user with control over proof steps that is similar to that found in an interactive theorem prover. Proofs that do not make use of the new experimental tactics should see no substantive changes, so this is expected to be a highly backward-compatible change.

  • The experimental and rarely-used goal_assume tactic has been removed. The use case it was targeting is better solved via sequents.

  • Support LLVM versions up to 16.

Bug fixes

v0.9

08 Oct 00:34
Compare
Choose a tag to compare

New Features

Several improvements have been made to JVM verification:

  • For method specs that do not specify a final value for a field or array element, it is now enforced that the method must leave that field or element unmodified. This ensures soundness of the resulting override for use in compositional verification.

  • New JVM setup commands have been introduced for writing partial specifications: jvm_modifies_field, jvm_modifies_static_field, jvm_modifies_elem, and jvm_modifies_array. Used in the post-condition section of a spec, these declare that the field or array in question may be modified by the method in an unspecified manner.

  • All jvm_ functions have all been promoted from "experimental" to "current" status, so that enable_experimental is no longer necessary for JVM verification.

  • The RPC API now includes methods for Java verification, as described here.

A new enable_lax_pointer_ordering function exists, which relaxes the restrictions that Crucible imposes on comparisons between pointers from different allocation blocks.

A SAW value of type Bool can now be brought into scope in Cryptol expressions as a value of type Bit.

A new hoist_ifs_in_goal proof tactic works like hoist_ifs but on the current goal in a proof script.

The verification summaries produced when specifying the -s flag now contain much more detailed information. When producing JSON output (-f json), the tool in the verif-viewer directory can be used to translate it to GraphViz format.

Two new experimental functions can evaluate SAWCore terms into simpler forms. The normalize_term function simplifies the given term by fully evaluating it with the SAWCore symbolic simulator but keeping it in SAWCore format. The extract_uninterp function allows certain uninterpreted functions to be replaced with extra inputs and constraints on those inputs, allowing propositional solvers to prove goals involving uninterpreted functions.

Changes

  • The linked-in version of ABC (based on the Haskell abcBridge library) has been removed. During the original planning for this removal, we marked commands based on this library as deprecated. In the end, we replaced all of them except cec with Haskell implementations, so no other commands have been removed, and the following commands are now "current" again:

    • abc (which now is the same as w4_abc_verilog)
    • load_aig
    • save_aig
    • save_aig_as_cnf
    • bitblast
    • write_aiger
    • write_cnf

    We have also implemented a w4_abc_aiger command that writes a Term in AIGER format and invokes ABC on it as an external process. This should be very similar to the original abc command. Note that the pure Haskell AIGER and CNF generation code has not been heavily tuned for performance, and could likely be made more efficient. Please file issues for performance regressions you encounter!

    The removal of the linked-in ABC version means that the abc tactic now requires an external abc executable. You can get this by downloading a with-solvers package from the releases page, by downloading a solver package from the what4-solvers repository, or by building it yourself from the ABC repository.

  • The LLVM bitcode reader now should support files from any LLVM version between 3.6 and 12.

  • Experimental Windows builds are again available. The --no-color option may be useful if you encounter I/O trouble running the REPL.

Bug Fixes

v0.8

20 Apr 23:27
Compare
Choose a tag to compare

New Features

SAW now includes experimental support for verifying Java code using JDK 9 or later. Verifying Java code that only uses primitive data types is known to work well, but code that imports certain classes (e.g., String) is known to suffer from issues documented here.

When verifying Java code, the path to Java can be specified with the new --java-bin-dirs/-b command-line option. Alternatively, if --java-bin-dirs is not set, then SAW searches the PATH to find Java. When the path to Java is known, SAW can automatically add system-related JAR files to the JAR path, which eliminates the need to manually specify these files with -j.

The Crucible-based interface to Java verification is now strictly an improvement over the older code base, with the addition of several features:

  • Performance of JVM verification is significantly better, as a result of removing some unnecessary instances of rewriting. This improves performance of LLVM verification, as well.

  • The new jvm_static_field_is function allows describing the contents of static variables in method specifications.

  • The verification code initializes all JVM classes at the start so that initializers don't run at arbitrary intermediate points and clobber static field values specified in preconditions. This means, however, that any proofs about Java code are under the assumption that all class initializers have run before the method under analysis executes.

Now that the Crucible-based verification infrastructure is sufficiently expressive and performant, we have removed all dependencies on the old jvm-verifier library.

On the LLVM side, SAWScript includes a variety of new functions for writing specification blocks:

  • The llvm_struct_type and llvm_packed_struct_type functions each construct an LLVM struct type from a list of other LLVM types. This is not to be confused with the existing llvm_struct function, which takes a string as an argument and returns the corresponding alias type (which is often, but not necessarily, defined as a struct type).

  • To avoid confusion, a new llvm_alias function now exists, and llvm_struct is now a synonym for llvm_alias. The llvm_struct function continues to be available for now.

  • The llvm_pointer : LLVMType -> LLVMType function allows construction of arbitrary LLVM pointer types.

  • Two new functions, llvm_points_to_at_type and llvm_conditional_points_to_at_type, mirror llvm_points_to and llvm_conditional_points_to, but cast the pointer to a different type. This may be useful when reading or writing a prefix of a larger array, for example.

  • Support for using ABC as an external process is more complete:

    • SAW can now generate Verilog with multiple outputs (from Term values that have tuple or vector result types, for example).

    • The new commands write_aig_external and write_cnf_external generate AIG and CNF files, respectively, by first writing Verilog and then using the available abc executable to bit-blast to the lower-level representation. Corresponding proof tactics, offline_aig_external and offline_cnf_external also exist.

These changes are in preparation for removing the linked-in copy of ABC in a future release.

The saw-remote-api RPC server and associated Python client now have more complete support for LLVM verification, including:

  • More complete points-to declarations, matching what is currently available in SAWScript.

  • Support for more provers, including the full range of SBV-based and What4-based provers available in SAWScript.

  • Support for ghost variables.

  • Support for assuming LLVM contracts directly (rather than the previous behavior which would temporarily assume that failed verifications succeeded to determine whether higher-level verifications would still succeed).

  • Support for global variables and initializers.

  • Support for null pointers.

  • Support for array value literals.

  • Support for specifying the value of individual struct fields and array elements.

  • Support for specifying the alignment of allocations.

Docker images for SAW are now located on GitHub instead of DockerHub.

Changes

The proof management infrastructure in SAWScript is simpler and more consistent than before. Many of these changes are internal, to make the code less error-prone and easier to maintain in the future. Several are user-facing, though:

  • The caseProofResult command now passes a Theorem argument to the first function argument, allowing its use as a rewrite rule, for example.

  • A new admit tactic exists, which takes a String argument describing why the user has decided omit proof of the goal. This replaces the assume_unsat and assume_valid tactics, which we now recommend against. They will be officially deprecated in a future release, and removed after that.

  • Prover tactics (e.g., yices) now return ProofScript () instead of ProofScript SatResult.

  • Simpsets can now contain "permutative" rewrite rules, where a rule is permutative if each side of the equality could represent the same set of terms and therefore the rule could repeatedly apply forever. A term ordering is used to prevent looping when these rules are applied.

Bug Fixes

v0.7

17 Dec 16:39
Compare
Choose a tag to compare

New Features

SAW can now use the ABC prover as an external process in addition to the linked-in version. This change is in preparation for removing the linked-in version in a future release. This change has several parts:

  • The new proof tactics w4_abc_verilog and w4_abc_smtlib2 allow using ABC to discharge proof goals using either Verilog or SMT-Lib2 as the intermediate file format, respectively.
  • The new offline_verilog tactic writes a proof goal in the subset of Verilog supported by ABC, which can allow the use of custom ABC commands to discharge it.
  • The new w4_offline_smtlib2 writes a proof goal in SMT-Lib2 syntax using What4 instead of SBV.
  • The new write_verilog command will write a Term to a file in Verilog syntax from the top level of a script.
  • The new write_smtlib2_w4 command will write a Term to a file in SMT-Lib2 syntax from the top level of a script, using What4 instead of SBV.
  • The new proof tactics sbv_abc, sbv_boolector, sbv_cvc4, sbv_mathsat, sbv_yices, sbv_z3, sbv_unint_cvc4, sbv_unint_yices, and sbv_unint_z3 are now aliases for the same tactics without the sbv_ prefixes in preparation for making the unprefixed tactics refer to the What4 versions of the same functionality.

Java verification using the Crucible symbolic execution engine is now more flexible and performant.

  • The new jvm_array_is command specifies the entire contents of an array together.
  • The new jvm_field_is command allows disambiguation by type for fields of the same name but different types.
  • JVM method names can be disambiguated using type descriptors.
  • JVM constructors can be referred to by the name <init>.
  • Error messages in JVM verification are significantly more helpful.

These changes, and various internal performance improvements, mean that the ECDSA verification example included with SAW now runs in around 5 minutes on a modern laptop.

New features exist to summarize any verifications performed with SAW. The summarize_verification command will print a list of all functions or methods verified or assumed, and all lemmas proved with commands such as prove. These summaries include the status (verified or assumed) of each item along with the provers used to complete the proof. The -s <filename> flag will instruct SAW to automatically write a summary to the given file, and the -f <format> flag will instruct SAW to use either a human-readable (pretty) format or JSON (json) for consumption by other tools.

An experimental RPC server for SAW now exists, which provides an alternative to SAWScript for controlling SAW execution. A client library for interacting with the server from Python exists here.

Verification of x86 code called from LLVM is now more flexible. The add_x86_preserved_reg command can add a specific register to the set that is assumed to be callee-saved, and path satisfiability checking is now performed when passing True as the fifth argument to crucible_llvm_verify_x86.

The new cryptol_add_path command adds a directory to the search path used when loading Cryptol modules (and following imports within explicitly-loaded modules).

New, shorter names are available for all LLVM commands starting with the crucible_ prefix. The new names use the llvm_ prefix instead. The top-level function crucible_llvm_verify is now llvm_verify, and crucible_llvm_unsafe_assume_spec is llvm_unsafe_assume_spec. The old names are still supported for now. The in-REPL documentation (:? <command>) gives the new name for each command.

Shorter names are available for some saw-script types: CrucibleSetup is now LLVMSetup, CrucibleMethodSpec is now simply LLVMSpec, and JVMMethodSpec is JVMSpec. The old type names are still supported for backward compatibility.

Bug Fixes

v0.6

02 Sep 17:04
Compare
Choose a tag to compare

New Features

  • Added experimental support for compositional extraction. Previously, crucible_llvm_extract and similar functions could translate very simple imperative functions into Term models but analysis of more complex programs typically required verification of equivalence to Cryptol specifications. Now, the crucible_llvm_compositional_extract function allows extraction of any function that can be specified using a CrucibleSetup block of the sort used for crucible_llvm_verify. In addition, this extraction can be compositional, preserving the call structure that exists in the original program instead of inlining everything.

  • Added experimental support for interactive offline proofs using Coq. The write_coq_term function and offline_coq tactic will export the associated Term to a file in Gallina syntax. This file can be imported into a Coq file that can do arbitrarily complex interactive proofs.

  • Added experimental support for arrays of symbolic size. The new crucible_array_alloc function specifies the existence of an allocated array where the size is given by its Term argument. The new crucible_points_to_array_prefix function specifies that the given pointer points to (the prefix of) a symbolic array value of a given symbolic size.

  • Improved x86 verification capabilities. Verification scripts for x86 functions can now process functions with mutable globals and function calls (which are currently inlined), and can use proof scripts to discharge proof obligations.

  • Added a new llvm_sizeof primitive, which works similarly to the sizeof operator in C.

  • Added support for the llvm.fshl.i32 funnel shift intrinsic.

  • Added experimental support for verification summaries. These summaries list all verifications performed within a script in a concise way that can track arbitrarily complex proof orchestrations. Future releases will include more information in these summaries, and more textual explanation of the assumptions made during each proof.

Other Changes

  • Made small improvements to documentation and error messages throughout.

  • Improved the performance of expression hashing (closing #674).

  • Updated to include Cryptol 2.9.1 and all the associated changes.

Bug Fixes

v0.5

29 Apr 00:24
Compare
Choose a tag to compare

New Features

  • Added experimental support for basic, non-compositional verification
    of x86 machine code for use in conjunction with LLVM verification.

      crucible_llvm_verify_x86 :
        LLVMModule -> String -> String ->
        [(String, Int)] -> Bool -> CrucibleSetup () ->
        TopLevel CrucibleMethodSpec
    

    The first argument specifies the LLVM module containing the caller.
    The second and third specify the ELF file name and symbol name of the
    function to be verifier. The fourth specifies the names and sizes (in
    bytes) of global variables to initialize, and the fifth whether to
    perform path satisfiability checking. The last argument is the LLVM
    specification of the calling context against which to verify the
    function.

  • Added support for using the SMT theory of arrays in the LLVM memory
    model. In some cases, this can significantly improve performance.

      enable_smt_array_memory_model : TopLevel ()
      disable_smt_array_memory_model : TopLevel ()
    
  • Added support for specifying alignment in LLVM allocations. The
    crucible_alloc_aligned and crucible_alloc_readonly_aligned
    functions allocate read-write and read-only memory regions,
    respectively, with the specified alignment (in bytes).

  • Added a conditional points-to function,
    crucible_conditional_points_to, that allows an LLVM function to
    conditionally modify memory, leaving it in its previous state
    (potentially uninitialized) when the condition is false.

  • Added several new options:

    • New functions enable_what4_hash_consing and
      disable_what4_hash_consing to enable or disable hash consing to
      increase sub-formula sharing during symbolic execution.

    • New functions enable_crucible_assert_then_assume and
      disable_crucible_assert_then_assume to control whether
      predicates are assumed after asserting them during symbolic
      execution. The default is now to not assume them, whereas
      previously they were assumed.

    • New command-line option --no-color to print an ASCII logo
      without ANSI color or Unicode.

Performance Improvements

  • Improved performance of the LLVM memory model.

  • Improved performance of bitvector operations during symbolic execution.

  • Improved performance of rewriting SAWCore terms.

Bug Fixes

  • Fixed SBV interface to fail more gracefully when it cannot find the
    solver executable.

  • Fixed SMT-Lib export negation issues.

Fixes issues #286, #489, #491, #564, #580, #583, #585, #586, #587, #590,
#592, #594, #597, #598, #602, #603, #612, #613, #622, #626, #633, #638,
#639, and #647.

v0.4

23 Oct 16:01
Compare
Choose a tag to compare
  • Fixed a long-standing soundness issue (#30) in compositional verification of LLVM programs. Previously, a specification for a function that neglected to mention an effect that the function in fact caused could be successfully verified. When verifying a caller of that function, only the effects mentioned in the specification would be used. The fix for this issue may break some proof scripts: any pointer mentioned using crucible_points_to in the initial state of a specification but not in the final state will be assigned a final value of "invalid", and any subsequent reads from the pointer will fail. To fix this issue, make sure that every specification you use provides a final value for every pointer it touches (which in many cases will be the same as its initial value).

  • Added an experimental command, llvm_boilerplate, that emits skeleton function specifications for every function defined in an LLVM module. The additional crucible_llvm_array_size_profile command can be used to refine the results of llvm_boilerplate based on the array sizes used by calls that arise from a call to the named top-level function.

  • Added support for using the symbolic execution profiler available in Crucible. The enable_crucible_profiling command causes profiling information to be written to the given directory. This can then be visualized using the rendering code available here.

  • Added proof tactics to use Yices (w4_unint_yices) and CVC4 (w4_unint_cvc4) through the What4 backend instead of SBV.

  • Modified the messages emitted for failed points-to assertions to be in terms of LLVM values.

  • Added support for using the SMT array memory model to reason about the LLVM heap. The enable_smt_array_memory_model command enables it for all future proofs.

  • LLVM bitcode format support is improved. Versions 3.5 to 9.0 are known to be mostly well-supported. We consider parsing failures with any version newer than 3.5 to be a bug, so please report them on GitHub.

  • New experimental model counting commands sharpSAT and approxmc bind to the external tools of the same name. These were mistakenly listed as included in 0.3.

  • Built against Cryptol 2.8.0.

  • Improved error messages in general.

  • Fixed various additional bugs, including #211, #455, #479, #484, #493, #496, #511, #521, #522, #534, #563

v0.3

29 May 17:30
a4eb932
Compare
Choose a tag to compare
  • Java and LLVM verification has been overhauled to use the new Crucible symbolic execution engine. Highlights include:

    • New crucible_llvm_verify and crucible_llvm_extract commands replace llvm_verify and llvm_extract, with a different structure for specification blocks.

    • LLVM verification tracks undefined behavior more carefully and has a more sophisicated memory model. See the manual for more.

    • New, experimental crucible_jvm_verify and crucible_java_extract commands will eventually replace java_verify and java_extract. For the moment, the former two are enabled with the enable_experimental command and the latter two are enabled with enable_deprecated.

    • More flexible specification language allows convenient description of functions that allocate memory, return arbitrary values, expect explicit aliasing, work with NULL pointers, cast between pointers and integers, or work with opaque pointers.

    • Ghost state is supported in LLVM verification, allowing reasoning about certain complex or unavailable code.

    • Verification of LLVM works for a larger subset of the language, which particularly improves support for C++.

  • LLVM bitcode format support is greatly improved. Versions 3.5 to 7.0 are known to be mostly well-supported. We consider parsing failures with any version newer than 3.5 to be a bug, so please report them on GitHub.

  • Greatly improved error messages throughout.

  • Built against Cryptol 2.7.0.

  • New model counting commands sharpSAT and approxmc bind to the external tools of the same name.

  • New proof script commands allow multiple goals and related proof tactics. See the manual.

  • Can be built with Docker, and will be available on DockerHub.

  • Includes an Emacs mode.