Skip to content

tpm2-attest subcommands

Usage: tpm2-attest subcommand [options...]

For more information see:



tpm2-attest quote [nonce] > quote.tar
scp quote.tar ...

After contacting the remote attestation server to receive the nonce, the machine will generate the endorsement key, endorsement cert, a one-time attestation key, and a signed quote for the all PCRs using that nonce (or the time of day, if no nonce is supplied).

The output quote.tar should be sent to the remote side for validation. There is nothing sensitive in the file, so it can be sent in clear text to the server.

TODO: the quote should be integrity protected, although while it does not weaken the protocol, it does allow an adversary to create spurious attestation failures.



tpm2-attest attest http://server/attest [nonce [pcrs,...]] > secret.txt

This will generate a quote for the nonce (or the current time if none is specified) and for the PCRs listed in the $QUOTE_PCRS environment variable. It will then send the quote to a simple attestation server, which will validate the quote and reply with a sealed message that can only be decrypted by this TPM on this boot.

No validation of the attestation server is done.



tpm2-attest verify quote.tar [nonce [ca-path]]

This will validate that the quote was signed with the attestation key with the provided nonce, and verify that the endorsement key from a valid TPM. It outputs, but does not validate the event log; use tpm2-attest eventlog-verify once the known PCRs are available, or use a more complex validation scheme.

If the nonce is not specified, the one in the quote file will be used, although this opens up the possibility of a replay attack. The QUOTE_MAX_AGE can be used to ensure that the quote is fresh.

If the ca-path is not specified, the system one will be used.

The output on stdout is yaml formatted with the sha256 hash of the DER format EK certificate, the validated quote PCRs, and the unvalidated eventlog PCRs.



tpm2-attest eventlog [eventlog.bin]

This will read and parse the TPM2 eventlog. If no file is specified, the default Linux one will be parsed. If - is specified, the eventlog will be read from stdin.



tpm2-attest eventlog-verify quote.tar [good-pcrs.txt]

This will verify that the PCRs included in the quote match the TPM event log, and if good-prcs.txt are passed in that they match those as well.



tpm2-attest ek-verify quote.tar ca-path

This will validate that the endorsement key came from a valid TPM.

The TPM endorsement key is signed by the manufacturer OEM key, which is in turn signed by a trusted root CA. Before trusting an attestation it is necessary to validate this chain of signatures to ensure that it came from a legitimate TPM, otherwise an attacker could send a quote that has a fake key and decrypt the message in software.

The ca-path should contain a file named roots.pem with the trusted root keys and have the hash symlinks created by c_rehash.

stdout is the sha256 hash of the DER format EK certificate.



tpm2-attest quote-verify quote.tar [nonce]

This command checks that the quote includes the given nonce and was signed by the public attestation key (AK) in the quote file. This also check the attributes of the AK to ensure that it has the correct bits set (fixedtpm, stclear, etc). NOTE: This does not verify that the AK came from a valid TPM. See tpm2-attest verify for the full validation.

If the nonce is not specified on the command line, the one in the quote file will be used. Note that this is a potential for a replay attack -- the remote attestation server should keep track of which nonce it used for this quote so that it can verify that the quote is actually live.

stdout is the yaml formatted tpm2 checkquote, which can be used to validate the eventlog PCRs.



echo secret | tpm2-attest seal quote.tar > cipher.bin

After a attested quote has been validated, an encrypted reply is sent to the machine with a sealed secret, which can be of arbitrary length, that is encrypted with a random key. This random key is encrypted with that machines endorsment key (ek.crt), along with the name of the attestation key used to sign the quote. The TPM will not decrypt the message key unless the attestation key was one that it generated.

The sealed.tar file should be sent back to the device being attested; it can then run tpm2-attest unseal < sealed.tar > secret.txt to extract the sealed secret (which may be of arbitrary length).



cat sealed.tar | tpm2-attest unseal > secret.txt

When the remote attestation has been successful, the remote machine will reply with an encrypted blob that is only unsealable by this TPM if and only if the EK matches and the AK is one that it generated.



tpm2-attest verify-and-seal quote.tar [nonce [pcrs]] < secret.txt > sealed.tar

If the nonce is not specified on the command line, the one in the quote file will be used. Note that this is a potential for a replay attack -- the remote attestation server should keep track of which nonce it used for this quote so that it can verify that the quote is actually live.



tpm2-attest ek-sign < ek.pem > ek.crt [/CN=device-name/]

Some TPMs do not include manufacturer signed endorsement key certificates, so it is necessary to extract the EK and sign it with a trusted key. This will produce ek.crt, signed with the safeboot key. The signing operation can be done out-of-band on a different machine.

For Google Cloud ShieldedVM machines see:

Usually the EK public components can be extracted from the TPM, signed, and the resulting signed ek.crt can be stored back into the TPM nvram. Note that this will erase an existing OEM cert if you have one!

# on the device
tpm2-attest ek-crt > ek.pem
# on the server
tpm2-attest ek-sign < ek.pem > ek.crt /CN=device/
# on the device again
tpm2-attest ek-crt ek.crt



tpm2-attest ek-crt > ek.pem  # Export the TPM EK in PEM format (not cert)


tpm2-attest ek-crt ek.crt  # Import a signed cert for the EK in DER format

Export the TPM RSA endorsement key for signing by a CA or import a signed endorsement key certificate into the TPM NVRAM at the well-known handle. See tpm2-attest ek-sign for more details.

Last update: June 21, 2021