Please reach out to sales@privy.io to enable access to this feature.
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.
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.
Requesting an attestation
Set theprivy-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.
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, theprivy-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 documentsmodule_id, timestamp, digest, pcrs, certificate, and cabundle. Two of those
fields behave in ways the AWS docs do not cover:
module_idchanges whenever Privy replaces an enclave, so it is not a stable deployment identity.public_keyis absent, because Privy does not use it for key exchange.
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
PCR0to 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
PCR0observed across requests and alert on a change. This detects an image change. But it does not show what the image contains.
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:- Strip the
deflate:prefix, base64-decode the remainder, and inflate it to raw CBOR bytes. - Decode the
COSE_Sign1structure, which is a four element array of protected header, unprotected header, payload, and signature. The payload is the CBOR attestation document. - 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 leafcertificate. This proves AWS issued the certificate. - Verify the
COSE_Sign1signature against the leaf certificate, then compareprivy_client_nonceandprivy_enclave_response_sha256inuser_dataagainst the nonce sent and the attested payload. This proves an enclave produced the response and that nothing altered it in flight. - Read
PCR0from 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.
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 thecbor
and @scure/base packages.
verify-attestation.ts
text() rather than json(),
because the hash covers the exact bytes Privy returned.
custody field, normalize it before hashing. Rebuild
the object rather than deleting from the parsed body, so that entity keeps its position:
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}/rpcandPOST /v1/wallets/rpc POST /v1/wallets/{wallet_id}/raw_sign
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_sendTransactionsignAndSendTransactiontron_sendTransactionwallet_sendCallseth_sign7702Authorization
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.

