diff --git a/NSym/proof/autospecs/README.md b/NSym/proof/autospecs/README.md index 5a3ff4ab..0294414b 100644 --- a/NSym/proof/autospecs/README.md +++ b/NSym/proof/autospecs/README.md @@ -1,13 +1,9 @@ # Autospecs -This dune package contains automatically generated Ocaml specifications and auxiliary Ocaml files associated with the automatically generated specifications. We use Cryptol specifications (for SAW proofs) as input and translate them into Ocaml specifications that work with NSym. Auxiliary Ocaml files contain functions or lemmas that are needed in the NSym proofs. We keep the automatically generated files in the repository to keep a record of them. +This dune package contains automatically generated Ocaml specifications. We use Cryptol specifications (for SAW proofs) as input and translate them into Ocaml specifications that work with NSym. We keep the automatically generated files in the repository to keep a record of them. ## SHA512 The automatically generated specifications include: 1. `SHA384rec.ml`: A translation from NSym/spec/SHA384rec.cry 2. `SHA512rec.ml`: A translation from NSym/spec/SHA512rec.cry - -The auxiliary files are: -1. `sha2.ml`: A parameterization of the NSym proofs to allow both SHA384 and SHA512 -2. `sha512rec_theorems.ml`: Base case and inductive case theorems for the recursive function `air_processBlocks_rec` diff --git a/README.md b/README.md index c022d650..0264a904 100644 --- a/README.md +++ b/README.md @@ -42,14 +42,14 @@ AWS libcrypto includes many cryptographic algorithm implementations for several | ECDH | with P-384 | EVP_PKEY_derive_init, EVP_PKEY_derive | SandyBridge+ | EC_Ops_Correct, MemCorrect, NoEngine, CRYPTO_refcount_Correct, PubKeyValid |[SAW](SAW/README.md) | | HKDF | with HMAC-SHA384 | HKDF_extract, HKDF_expand, HKDF | SandyBridge+ | MemCorrect, NoEngine, NoInline, OutputLength, CRYPTO_once_Correct |[SAW](SAW/README.md) | -The platforms for which code is verified are defined in the following table. In all cases, the actual verification is performed on code that is produced by Clang 14 (for neoverse-v1 cross-compilation) and Clang 10, but the verification results also apply to any compiler that produces semantically equivalent code. +The platforms for which code is verified are defined in the following table. In all cases, the actual verification is performed on code that is produced by Clang 14 (for cross-compilation to AArch64) and Clang 10, but the verification results also apply to any compiler that produces semantically equivalent code. | Platform | Description | | --------------- | ------------| -| SandyBridge+ | x86-64 with AES-NI, CLMUL, and AVX. Compile switches: check SAW/scripts/x86_64/build_llvm.sh and SAW/scripts/x86_64/build_x86.sh -| SandyBridge-Skylake | x86-64 with AES-NI, CLMUL, and AVX, but not AVX-512. Compile switches: check SAW/scripts/x86_64/build_llvm.sh and SAW/scripts/x86_64/build_x86.sh -| neoverse-n1 | aarch64 without SHA512. Compile switches: check SAW/scripts/aarch64/build_llvm.sh and NSym/scripts/build_aarch64.sh -| neoverse-v1 | aarch64 with SHA512. Compile switches: check SAW/scripts/aarch64/build_llvm.sh and NSym/scripts/build_aarch64.sh +| SandyBridge+ | x86-64 with AES-NI, CLMUL, and AVX. Compile switches: see [build_llvm.sh](SAW/scripts/x86_64/build_llvm.sh) and [build_x86.sh](SAW/scripts/x86_64/build_x86.sh) +| SandyBridge-Skylake | x86-64 with AES-NI, CLMUL, and AVX, but not AVX-512. Compile switches: see [build_llvm.sh](SAW/scripts/x86_64/build_llvm.sh) and [build_x86.sh](SAW/scripts/x86_64/build_x86.sh) +| neoverse-n1 | aarch64 without SHA512. Compile switches: see [build_llvm.sh](SAW/scripts/aarch64/build_llvm.sh) and [build_aarch64.sh](NSym/scripts/build_aarch64.sh) +| neoverse-v1 | aarch64 with SHA512. Compile switches: see [build_llvm.sh](SAW/scripts/aarch64/build_llvm.sh) and [build_aarch64.sh](NSym/scripts/build_aarch64.sh) The caveats associated with some of the verification results are defined in the table below. @@ -102,6 +102,9 @@ SAW's breakpoint feature for invariant proof capability requires all local varia | -------- | ------------------ | ------ | | `ec_GFp_nistp384_point_mul_public` | EC | This function has a loop that is computationally hard for SAW. We use SAW's breakpoint feature to conduct invariant proof instead of doing loop-unrolling. | +## Specification + +The [SPEC.md](SPEC.md) file contains specifications for each verified implementation. ## License diff --git a/SPEC.md b/SPEC.md new file mode 100644 index 00000000..8e8d0898 --- /dev/null +++ b/SPEC.md @@ -0,0 +1,90 @@ +# AWS libcrypto Verification +This repository contains specifications and correctness proofs for a set of cryptographic functions in [AWS libcrypto](https://github.com/awslabs/aws-lc). + +C and X86_64 proofs are carried out in [SAW](https://saw.galois.com/) using [Cryptol](https://cryptol.net/) specifications stored in the [Galois Cryptol spec repository](https://github.com/GaloisInc/cryptol-specs). AArch64 proofs are carried out in NSym using translated specifications written in Cryptol. Coq proofs are developed for verifying properties of the Cryptol specifications. + +## Specification + +This section describes high-level specification for verified implementations. + +### SHA-2 + +The EVP_Digest* functions are verified to have the following properties related to SHA-2. For more detailed specifications, see [evp-function-specs.saw](proof/SHA512/evp-function-specs.saw). BLOCK_LENGTH is the block length of the hash function, in bytes. DIGEST_LENGTH is the digest length of the hash function, in bytes. For example, for SHA-384, BLOCK_LENGTH is 64 and DIGEST_LENGTH is 48. + +| Function | Preconditions | Postconditions | +| ---------------| -------------| --------------- | +| EVP_DigestInit | | | +| EVP_DigestUpdate | | | +| EVP_DigestFinal | | | + +### HMAC with SHA-384 + +The HMAC_* functions are verified to have the following properties related to HMAC with SHA-384. For more detailed specifications, see [HMAC-array.saw](proof/HMAC/HMAC-array.saw). BLOCK_LENGTH is the block length of the hash function, in bytes. DIGEST_LENGTH is the digest length of the hash function, in bytes. For SHA-384, BLOCK_LENGTH is 64 and DIGEST_LENGTH is 48. + +| Function | Preconditions | Postconditions | +| ---------------| -------------| --------------- | +| HMAC_CTX_init | | | +| HMAC_Init_ex | | | +| HMAC_Update | | | +| HMAC_Final | | | +| HMAC | | | + +### AES-KW(P) + +The AES_(un)wrap_key_* functions are verified to have the following properties related to AES Key Wrap (and AES Key Wrap with Padding) using AES-256. These operations are defined in [NIST SP 800-38F](https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-38F.pdf). For more detailed specifications, see [AES_KW.saw](proof/AES_KW/AES_KW.saw). + +| Function | Preconditions | Postconditions | +| ---------------| -------------| --------------- | +| AES_wrap_key | | | +| AES_unwrap_key | | | +| AES_wrap_key_padded | | | +| AES_unwrap_key_padded | | | + +### Elliptic Curve Keys and Parameters + +The EVP_PKEY_* functions are verified to have the following properties related to EC using P-384. For more detailed specifications, see [evp-function-specs.saw](proof/ECDH/evp-function-specs.saw). + +| Function | Preconditions | Postconditions | +| ----------| --------------| --------------- | +| EVP_PKEY_CTX_new_id | | | +| EVP_PKEY_CTX_new | | | +| EVP_PKEY_paramgen_init | | | +| EVP_PKEY_CTX_set_ec_paramgen_curve_nid | | | +| EVP_PKEY_paramgen | | | +| EVP_PKEY_keygen_init | | | +| EVP_PKEY_keygen | | | + +### ECDSA + +The EVP_DigestSign*/EVP_DigestVerify* functions are verified to have the following properties related to ECDSA using P-384 and SHA-384. For more detailed specifications, see [evp-function-specs.saw](proof/ECDSA/evp-function-specs.saw). BLOCK_LENGTH is the block length of the hash function, in bytes. MAX_SIGNATURE_LENGTH is the maximum length of the signature in ASN1 format, in bytes. For ECDSA with P-384 and SHA-384, BLOCK_LENGTH is 64 and MAX_SIGNATURE_LENGTH is 104. + +| Function | Preconditions | Postconditions | +| ----------| --------------| --------------- | +| EVP_DigestSignInit | | | +| EVP_DigestVerifyInit | | | +| EVP_DigestSignUpdate | | | +| EVP_DigestVerifyUpdate | | | +| EVP_DigestSignFinal | | | +| EVP_DigestVerifyFinal | | | +| EVP_DigestSign | | | +| EVP_DigestVerify | | | + +### ECDH + +The EVP_PKEY_derive* functions are verified to have the following properties related to ECDH using P-384. For more detailed specifications, see [evp-function-specs.saw](proof/ECDH/evp-function-specs.saw). + +| Function | Preconditions | Postconditions | +| ----------| --------------| --------------- | +| EVP_PKEY_derive_init | | | +| EVP_PKEY_derive_set_peer_spec | | | +| EVP_PKEY_derive | | | + +### HKDF with HMAC-SHA384 + +The HKDF_* functions are verified to have the following properties related to HKDF with HMAC-SHA384. For more detailed specifications, see [HKDF.saw](proof/KDF/HKDF.saw). DIGEST_LENGTH is the digest length of the hash function, in bytes. For HMAC-SHA384, DIGEST_LENGTH is 48. + +| Function | Preconditions | Postconditions | +| ---------------| -------------| --------------- | +| HKDF_extract | | | +| HKDF_expand | | | +| HKDF | | |