Skip to main content
Please reach out to sales@privy.io to enable access to this feature.
Privy signs wallet operations inside an AWS Nitro Enclave. Setting a header on a supported request returns a Nitro attestation document alongside the response. An app verifies that document to confirm the operation ran inside the enclave.

Request an attestation

Set the nonce header and read the document from the response.

Verify an attestation

Check the certificate chain, signature, nonce, and response hash.

Supported operations

See which endpoints attest their responses today.

Two levels of verification

Attestation supports two checks. Each one proves something different. Signature verification is self-serve. An app sets a header, pulls the AWS Nitro root certificate, and checks the document. This proves three facts:
  • Nitro hardware. A certificate chain rooted in the AWS Nitro Enclaves root certificate signs the document, so it came from real Nitro hardware.
  • Response binding. The enclave hashed the operation result into the document, so the attested result cannot be swapped for a different one after the fact.
  • Freshness. The enclave echoed the caller’s nonce into the document, so a previously captured attestation cannot be replayed for a new request.
Code verification also binds the response to a known Privy enclave build. It compares the attested PCR0 value against an image Privy supplies. This check is not self-serve. Privy grants access to its AWS account so that an app can pull enclave builds.
Signature verification alone proves that some Nitro enclave signed the response, not that Privy’s enclave signed it. An attacker running their own Nitro Enclave could intercept a request and return a substituted document that passes every signature check. Closing that gap requires verifying the enclave code, which Privy supports on request.

Requesting an attestation

Set the privy-enclave-attestation-nonce header on a supported request. The nonce must be 8 to 128 characters, using alphanumeric, base64 (+, /, =), dash, or underscore characters. Apps should use a fresh random nonce per request.
The enclave returns the document in the privy-enclave-signature response header, formatted as deflate:<base64>. The value is a deflate-compressed, base64-encoded CBOR attestation document. Requests that omit the nonce header behave exactly as before. The enclave then builds nothing.

Error values

When the enclave cannot build a document, the privy-enclave-signature header carries an error code. The request itself still succeeds, so apps that require attestation must check the header.

Document contents

Once decoded, the document follows the AWS Nitro attestation format. AWS sets and documents module_id, timestamp, digest, pcrs, certificate, and cabundle. Two of those fields behave in ways the AWS docs do not cover:
  • module_id changes whenever Privy replaces an enclave, so it is not a stable deployment identity.
  • public_key is absent, because Privy does not use it for key exchange.
Privy controls the remaining two fields:

Verifying the enclave code

Platform configuration registers (PCRs) measure what the enclave booted. PCR0 measures the entire enclave image file, so it identifies the exact image that ran. It is also the value Privy’s KMS key policy is bound to. Secrets only decrypt for an image whose PCR0 matches the approved value. AWS documents the remaining registers under cryptographic attestation. Comparing PCR0 against a known-good value is what proves the enclave ran Privy’s code. Privy does not publish those values, so an app has two options:
  • Reproducible build. Privy supplies the Docker image for an enclave release on request. Build the enclave image file from it, then compare the resulting PCR0 to the attested value. The enclave build is deterministic, so a match shows exactly which code signed the response. Ask for an image at security@privy.io.
  • Pinning. Record the PCR0 observed across requests and alert on a change. This detects an image change. But it does not show what the image contains.
Nitro keys registers by integer, so pcrs may decode as a Map rather than a plain object. Read index 0 for PCR0 and hex-encode the bytes before comparing.

User data

user_data holds a JSON object with four fields:
The two key hashes describe the enclave deployment rather than the request. They stay the same until the enclave’s key material changes. Recording them across requests therefore lets an app detect a rotation or an unexpected change in key setup.

Verifying the document

Verification has five steps:
  1. Strip the deflate: prefix, base64-decode the remainder, and inflate it to raw CBOR bytes.
  2. Decode the COSE_Sign1 structure, which is a four element array of protected header, unprotected header, payload, and signature. The payload is the CBOR attestation document.
  3. Validate the certificate chain. Confirm that cabundle[0] is the AWS Nitro Enclaves root certificate, that each certificate’s predecessor signed it, and that the final bundle entry signed the leaf certificate. This proves AWS issued the certificate.
  4. Verify the COSE_Sign1 signature against the leaf certificate, then compare privy_client_nonce and privy_enclave_response_sha256 in user_data against the nonce sent and the attested payload. This proves an enclave produced the response and that nothing altered it in flight.
  5. Read PCR0 from the document, then compare or pin it as described under verifying the enclave code. Skipping this step leaves the response unbound from Privy’s enclave.
Steps 1 through 4 use standard Nitro primitives, which AWS covers in verifying the root of trust. Two details matter here. The COSE_Sign1 signature is ES384 over the CBOR encoding of ["Signature1", protectedHeader, <empty bytes>, payload] (RFC 8152 section 4.4). The raw 96-byte value needs DER conversion first. And cabundle[0] must match the AWS Nitro Enclaves root certificate (Root-G1). AWS publishes it at https://aws-nitro-enclaves.amazonaws.com/AWS_NitroEnclaves_Root-G1.zip, with this SHA-256 fingerprint:

Example

This example verifies an attestation returned with a wallet creation response. It requires the cbor and @scure/base packages.
verify-attestation.ts
Calling it for wallet creation looks like this. Read the response with text() rather than json(), because the hash covers the exact bytes Privy returned.
If the response carries an entity object or a custody field, normalize it before hashing. Rebuild the object rather than deleting from the parsed body, so that entity keeps its position:
For most endpoints the attested payload is a minimal projection of the result rather than the full response body. A personal_sign response, for example, attests JSON.stringify({signature: body.data.signature}). Privy supplies the exact projection for each operation on request.

Supported operations

Attestation is currently available on:
  • Wallet creation, wallet updates, and wallet deletion
  • Key quorum creation, updates, and deletion
  • Signing methods on POST /v1/wallets/{wallet_id}/rpc and POST /v1/wallets/rpc
  • POST /v1/wallets/{wallet_id}/raw_sign
Policy creation and updates, policy rule changes, batch wallet creation, and POST /v1/users/{user_id}/wallets do not attest their responses yet. Requesting attestation on those endpoints returns attestation-not-supported. To attest a wallet creation, call the single wallet creation endpoint instead.

Methods that cannot be verified

These methods do more than sign. The enclave signs, then Privy performs work outside the enclave such as nonce management, gas sponsorship, or broadcasting:
  • eth_sendTransaction
  • signAndSendTransaction
  • tron_sendTransaction
  • wallet_sendCalls
  • eth_sign7702Authorization
The enclave does attest the signing step. But the response body returns the result of the wider operation, not the signed artifact. An app cannot rebuild the attested payload, so the hash check cannot pass.
To attest a transaction, sign it with eth_signTransaction, signTransaction for Solana, or tron_signTransaction, verify the attestation, then broadcast the signed transaction separately.

Limitations

  • The attestation travels in a response header, so an app must read the header and the body from the same response. Privy’s server SDKs do not expose the header, so verification requires a raw HTTP client.
  • The enclave builds each attestation on demand and keeps no copy. Apps that need an audit trail should store the header value alongside the response they verified.
  • Attestation failures never fail the underlying request. Apps that treat attestation as mandatory must enforce that themselves.
Questions about attestation, or about verifying a specific document, can go to security@privy.io.