Crate turnkey_proofs

Crate turnkey_proofs 

Source
Expand description

§turnkey_proofs

This crate contains utilities to parse and verify Turnkey secure enclave proofs. To learn more about Turnkey verification, check out our Turnkey Verified docs. As outlined in that doc, there are two types of proofs:

  • App proofs, signing structured data with enclave ephemeral keys.
  • Boot proofs, which are proofs that a given enclave was provisioned correctly. Boot proofs reference via their public_key field the enclave ephemeral key. This links App and Boot proofs together.

§Boot proofs

Boot Proof: a proof that a particular AWS Nitro Enclave booted with a particular configuration.

A boot proof contains

  • AWS attestation document, which contains PCR measurements, a ceritifaction chain that proves the document was signed by AWS’s root cert, a public key which is the ephemeral key unique to this particular enclave, and hash of the QOS Manifest
  • A signed QOS Manifest, the validity of which is attested to by the Attestation Document. A hash of the application binary, the quorum public key, and more.

Resources on AWS Nitro Enclaves, attestations, and verifying attestations can be found at the following:

§App Proofs

App Proof: a signature by an enclave ephemeral key to prove application-specific facts about functionality. An app proof, when combined with a boot proof, proves that your request was process:

  • in the context of your Turnkey organization
  • with Turnkey’s signer application
  • inside of a legitimate and precise version of QuorumOS
  • inside of a legitimate AWS Nitro Enclave
  • inside Turnkey’s canonical AWS production account

§Usage

§Verifying App Proofs

Given an app proof, you can request the boot proof for that app proof using get_boot_proof_for_app_proof.

To verify the app proof in conjunction with the boot proof, you call verify(appProof, bootProof). This verification goes through the following steps:

  • Verify app proof signature
  • Verify the boot proof
    • Attestation doc was signed by AWS
    • Attestation doc’s user_data is the hash of the qos manifest
  • Verify the app proof / boot proof connection - that the ephemeral keys match

§Attestation Document Verification

If you have a Turnkey organization you can request a an attestation document from Amazon, signed by a root certificate associated with AWS Nitro Attestation PKI (located in aws_root.pem). This top-level certificate can be downloaded from https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip.

You may request a fresh attestation with the turnkey CLI (available here):

$ turnkey request --host api.turnkey.com --path /public/v1/query/get_attestation --body '{ "organizationId": "<your organization ID>", "enclaveType": "signer" }' --organization <your organization ID>

{
   "attestationDocument": "<base64-encoded attestation document>"
}

This crate contains a function to parse and verify this attestation: parse_and_verify_aws_nitro_attestation. This returns an AttestationDoc containing PCR values. You can display these values like so:

use hex;
use turnkey_proofs::parse_and_verify_aws_nitro_attestation;

let attestation_document = "<base64-encoded attestation doc>".to_string();
let attestation = parse_and_verify_aws_nitro_attestation(attestation_document, None)
   .expect("cannot parse and verify attestation document");

// Display PCR values
println!("PCR0: {}", hex::encode(attestation.pcrs.get(&0).unwrap()));
println!("PCR1: {}", hex::encode(attestation.pcrs.get(&1).unwrap()));
println!("PCR2: {}", hex::encode(attestation.pcrs.get(&2).unwrap()));
println!("PCR3: {}", hex::encode(attestation.pcrs.get(&3).unwrap()));

// Display user data and public key fields
println!("user_data: {}", hex::encode(attestation.user_data.unwrap()));
println!(
   "public_key: {}",
   hex::encode(attestation.public_key.unwrap())
);

Head over to the QuorumOS repository if you’re looking to reproduce these PCR values independently.

Enums§

AppProofError
AppProof error.
AttestError
Attestation error.
BootProofError
BootProofError
VerifyError
Verify error.

Constants§

AWS_ROOT_CERT_PEM
AWS Nitro root CA certificate.
EXPECTED_EPHEMERAL_PUBLIC_KEY_LENGTH

Functions§

cert_from_pem
Extract a DER encoded certificate from bytes representing a PEM encoded certificate.
get_app_proof_time
get_boot_proof_for_app_proof
Wrapper around TurnkeyClient::get_boot_proof that fetches the boot proof for the given app proof
get_boot_proof_time
parse_and_verify_aws_nitro_attestation
Parses and verifies an AWS nitro attestation, provided as a base64 encoded string (defaults to using current time for validation)
parse_and_verify_der_attestation
Extract the DER encoded AttestationDoc from the nitro secure module (nsm) provided COSE Sign1 structure. This function will verify the the root certificate authority via the CA bundle and verify that the end entity certificate signed the COSE Sign1 structure.
unsafe_attestation_doc_from_der
Extract the DER encoded AttestationDoc from the nitro secure module (nsm) provided COSE Sign1 structure.
verify
Verify the app proof boot proof pair.
verify_app_proof_signature
Verify the app proof’s signature
verify_attestation_doc_against_user_input
Verify that attestation_doc matches the specified parameters.