Skip to main content

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 approved manifest envelope and configuration.

A boot proof contains

  • AWS attestation document, which contains PCR measurements, a certification 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 user_data containing the approved QOS manifest hash.
  • A QOS manifest and manifest envelope. The envelope is the authoritative source for the schema-aware manifest hash and approval set; the standalone manifest is checked for consistency with that envelope.

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 processed:

  • by the enclave ephemeral key named in the AWS attestation document
  • inside of an AWS Nitro Enclave whose attestation chain verifies to the AWS Nitro root
  • with PCR measurements, including the live manifest/key commitment, that match the approved QOS manifest envelope
  • with a standalone QOS manifest that is consistent with the approved manifest envelope

This is a cryptographic self-consistency and AWS enclave authenticity claim. It is not, by itself, a global proof that a manifest set is the canonical Turnkey production manifest set. Callers that need that claim must pin or independently obtain the expected manifest policy, operator set, or other Turnkey trust anchor they intend to trust.

§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
    • Manifest envelope approvals are internally valid
    • Standalone QOS manifest hash matches the manifest envelope hash
    • Attestation doc’s user_data is the approved manifest envelope hash
    • Attestation PCRs match the manifest enclave PCRs and PCR17 live manifest/key commitment
  • 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()));
println!("PCR16: {}", hex::encode(attestation.pcrs.get(&16).unwrap()));
println!("PCR17: {}", hex::encode(attestation.pcrs.get(&17).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())
);

For full QoS manifest verification of a parsed attestation document, use the phase-specific helpers re-exported from QoS: verify_attestation_doc_against_manifest_live checks the live/app manifest/key commitment in PCR17 and is almost always the right choice for application proof verification. verify_attestation_doc_against_manifest_setup checks the setup/boot manifest/key commitment in PCR16 for provisioning and bootstrap flows.

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

Structs§

ManifestAttestationInput
Expected values for manifest-backed attestation verification.

Enums§

AppProofError
AppProof error.
AttestError
Attestation error.
BootProofError
BootProofError
QosAttestError
Attestation error.
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_manifest_live
Verify a live/app QOS attestation document.
verify_attestation_doc_against_manifest_setup
Verify a setup/boot QOS attestation document.