From 3b4191c0ae7854f02f13a6be587027e082eeda37 Mon Sep 17 00:00:00 2001 From: Nicolas Williams Date: Wed, 19 May 2021 16:15:27 -0500 Subject: [PATCH] Expand on restricted keys; describe more TPM commands --- Attestation/README.md | 34 ++++---- Intro/README.md | 86 +++++++++++++------ .../TPM2_ActivateCredential.md | 0 TPM-Commands/TPM2_Certify.md | 21 +++++ TPM-Commands/TPM2_Duplicate.md | 25 ++++++ TPM-Commands/TPM2_Import.md | 22 +++++ TPM-Commands/TPM2_Load.md | 19 ++++ .../TPM2_MakeCredential.md | 0 {Attestation => TPM-Commands}/TPM2_Quote.md | 0 9 files changed, 164 insertions(+), 43 deletions(-) rename {Attestation => TPM-Commands}/TPM2_ActivateCredential.md (100%) create mode 100644 TPM-Commands/TPM2_Certify.md create mode 100644 TPM-Commands/TPM2_Duplicate.md create mode 100644 TPM-Commands/TPM2_Import.md create mode 100644 TPM-Commands/TPM2_Load.md rename {Attestation => TPM-Commands}/TPM2_MakeCredential.md (100%) rename {Attestation => TPM-Commands}/TPM2_Quote.md (100%) diff --git a/Attestation/README.md b/Attestation/README.md index 6937b2f..c8db741 100644 --- a/Attestation/README.md +++ b/Attestation/README.md @@ -95,10 +95,10 @@ key) encrypted to the EKpub and then the attestation client demonstrate that it was able to decrypt that with the EK. However, this is not _quite_ how attestation protocols work! Instead of plain asymmetric encryption the server will use -[`TPM2_MakeCredential()`](TPM2_MakeCredential.md), while the attestation -client will use -[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) instead of -plain asymmetric decryption. +[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md), while +the attestation client will use +[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) +instead of plain asymmetric decryption. ## Trusted State Attestation @@ -114,15 +114,15 @@ Typically the attestation protocol will have the client generate a signing-only asymmetric public key pair known as the attestation key (AK) with which to sign the PCR quote and eventlog. Binding of the EKpub and AKpub will happen via -[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) / -[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md). +[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) / +[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md). -Note that the [`TPM2_Quote()`](TPM2_Quote.md) function produces a signed +Note that the [`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md) function produces a signed message -- signed with a TPM-resident AK named by the caller (and to which they have access), which would be the AK used in the attestation protocol. -The output of [`TPM2_Quote()`](TPM2_Quote.md) might be the only part of +The output of [`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md) might be the only part of a client's messages to the attestation service that include a signature made with the AK, but integrity protection of everything else can be implied (e.g., the eventlog and PCR values are used to reconstruct the @@ -140,14 +140,14 @@ digest of the selected PCRs. `TPM2_Quote()` signs all of: ## Binding of Other Keys to EKpub -The semantics of [`TPM2_MakeCredential()`](TPM2_MakeCredential.md) / -[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) make it +The semantics of [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) / +[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) make it possible to bind a TPM-resident object to the TPM's EKpub. -[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) encrypts to the EKpub +[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) encrypts to the EKpub a small secret datum and the name (digest of public part) of the TPM-resident object being bound. The counter-part to this, -[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md), will decrypt +[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md), will decrypt that and return the secret to the application IFF (if and only if) the caller has access to the named object. @@ -195,14 +195,14 @@ Let's start with few observations and security considerations: timestamps. - Replay protection of server to client responses is mostly either not - needed or implicitly provided by [`TPM2_MakeCredential()`](TMP2_MakeCredential.md) + needed or implicitly provided by [`TPM2_MakeCredential()`](TPM2_MakeCredential.md) because `TPM2_MakeCredential()` generates a secret seed that randomizes its outputs even when all the inputs are the same across multiple calls to it. - Ultimately the protocol *must* make use of - [`TPM2_MakeCredential()`](TMP2_MakeCredential.md) and - [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) in order to + [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and + [`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) in order to authenticate a TPM-running host via its TPM's EKpub. - Privacy protection of client identifiers may be needed, in which case @@ -288,7 +288,7 @@ protocol: ![Protocol Diagram](Protocol-Two-Messages.png) (In this diagram we show the use of a TPM simulator on the server side -for implementing [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).) +for implementing [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).) The server will validate that the `timestamp` is near the current time, the EKcert (if provided, else the EKpub), the signature using the @@ -340,7 +340,7 @@ desirable anyways for monitoring and alerting purposes. ![Protocol Diagram](Protocol-Three-Messages.png) (In this diagram we show the use of a TPM simulator on the server side -for implementing [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).) +for implementing [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).) NOTE well that in this protocol, like single round trip attestation protocols using only decrypt-only EKs, it is *essential* that the AKcert diff --git a/Intro/README.md b/Intro/README.md index d3efdd0..b788f2b 100644 --- a/Intro/README.md +++ b/Intro/README.md @@ -291,16 +291,18 @@ necessarily yields a new name. > restricted keys. Still, it may be useful to illustrate cryptographic > object naming with one particularly important use of it. -A pair of functions, `TPM2_MakeCredential()` and -`TPM2_ActivateCredential()`, illustrate the use of cryptographic object -naming as a binding or a sort of authorization function. +A pair of functions, +[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and +[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md), +illustrate the use of cryptographic object naming as a binding or a sort +of authorization function. -`TPM2_MakeCredential()` can be used to encrypt a datum (a "credential") -to a target TPM such that the target will _only be willing to decrypt -it_ if *and only if* the application calling `TPM2_ActivateCredential()` -to decrypt that credential has access to some key named by the sender, -and that name is a cryptographic name that the sender can and must -compute for itself. +[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) can be +used to encrypt a datum (a "credential") to a target TPM such that the +target will _only be willing to decrypt it_ if *and only if* the +application calling `TPM2_ActivateCredential()` to decrypt that +credential has access to some key named by the sender, and that name is +a cryptographic name that the sender can and must compute for itself. The semantics of these two functions can be used to defeat a cut-and-paste attack in attestation protocols. @@ -312,21 +314,21 @@ keys, each with zero, one, or more children keys: ``` seed - | - | - v + /|\ + / | \ + v v v primary key (asymmetric encryption) - | - | - v + /|\ + / | \ + v v v secondary keys (of any kind) - | - | - v + /|\ + / | \ + v v v ... ``` -Note that every key has a parent or is a primary key. +Keys that have no parent are primary keys. There are four built-in hierarchies: @@ -540,21 +542,53 @@ Cryptographic keys can either be unrestricted or restricted. An unrestricted signing key can be used to sign arbitrary content. +An unrestricted decryption key can be used to decrypt arbitrary +ciphertexts encrypted to that key's public key. + +> NOTE WELL: The endorsement key (EK) is a restricted key. + +### Restricted Signing Keys + A restricted signing key can be used to sign only TPM-generated content as part of specific TPM restricted signing commands. Such content always begins with a magic byte sequence. Conversely, the TPM refuses to sign externally generated content that starts with that magic byte -sequence. +sequence. See the [`TPM2_Certify()`](/TPM-Commands/TPM2_Certify.md), +[`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md), `TPM2_CertifyCreation()`, +`TPM2_GetSessionAuditDigest()`, and `TPM2_GetCommandAuditDigest()` TPM +commands. + +There is also a notion of signing keys that can only be used to sign +PKIX certificates using `TPM2_CertifyX509()`. + +### Restricted Decryption Keys + +> NOTE WELL: The endorsement key (EK) is a restricted key. A restricted decryption key can only be used to decrypt ciphertexts whose plaintexts have a certain structure. In particular these are used -for `TPM2_MakeCredential()`/`TPM2_ActivateCredential()` to allow the -TPM-using application to get the plaintext if and only if (IFF) the -plaintext cryptographically names an object that the application has -access to. This is used to communicate secrets ("credentials") to TPMs. +for [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) / +[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) +to allow the TPM-using application to get the plaintext if and only if +(IFF) the plaintext cryptographically names an object that the +application has access to. This is used to communicate secrets +("credentials") to TPMs. -There is also a notion of signing keys that can only be used to sign -PKIX certificates. +Another operation that a restricted decryption key can perform is +[`TPM2_Import()`](/TPM-Commands/TPM2_Import.md), which decrypts a key +wrapped to the given decrypt-only key and outputs a file that can be +loaded with [`TPM2_Load()`](/TPM-Commands/TPM2_Load.md). The wrapped +key payload given to [`TPM2_Import()`](/TPM-Commands/TPM2_Import.md) too +has a particular structure and is produced by a remote peer using +[`TPM2_Duplicate()`](/TPM-Commands/TPM2_Duplicate.md). + +To recap, a restricted decryption key can only be used to: + + - "activate credentials" (made with + [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md)) + + - receive wrapped keys sent by a peer (made with + [`TPM2_Duplicate()`](/TPM-Commands/TPM2_Duplicate.md)) ## Attestation diff --git a/Attestation/TPM2_ActivateCredential.md b/TPM-Commands/TPM2_ActivateCredential.md similarity index 100% rename from Attestation/TPM2_ActivateCredential.md rename to TPM-Commands/TPM2_ActivateCredential.md diff --git a/TPM-Commands/TPM2_Certify.md b/TPM-Commands/TPM2_Certify.md new file mode 100644 index 0000000..8140382 --- /dev/null +++ b/TPM-Commands/TPM2_Certify.md @@ -0,0 +1,21 @@ +# `TPM2_Certify()` + +`TPM2_Certify()` signs an assertion that some named object is loaded in +the TPM. + +## Inputs + + - `TPMI_DH_OBJECT objectHandle` (object to be certified) + - `TPMI_DH_OBJECT signHandle` (handle for a signing key) + - `TPM2B_DATA qualifyingData` (extra data) + - `TPMT_SIG_SCHEME inScheme` ("signing scheme to use if the schemefor signHandleis `TPM_ALG_NULL`") + +## Outputs (success case) + + - `TPM2B_ATTEST certifyInfo` (what was signed) + - `TPMT_SIGNATURE signature` (signature) + +## References + + - [TCG TPM Library part 3: Commands, section 18.2](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf) + diff --git a/TPM-Commands/TPM2_Duplicate.md b/TPM-Commands/TPM2_Duplicate.md new file mode 100644 index 0000000..4b11640 --- /dev/null +++ b/TPM-Commands/TPM2_Duplicate.md @@ -0,0 +1,25 @@ +# `TPM2_Duplicate()` + +`TPM2_Duplicate()` wraps a key, typically encrypting it to a public key +for a key on a remote TPM. + +I.e., this is used to export a wrapped key for some target, typically a +remote TPM. + +## Inputs + + - `TPMI_DH_OBJECT objectHandle` (handle for key to encrypt with) + - `TPMI_DH_OBJECT newParentHandle` (optional; handle for key to wrap to -- "Only the public area of newParentHandle is required to be loaded") + - `TPM2B_DATA encryptionKeyIn` (optional; symmetric key to encrypt with) + - `TPMT_SYM_DEF_OBJECT+ symmetricAlg` ("definition for the symmetric algorithm to be used for the inner wrapper") + +## Outputs (success case) + + - `TPM2B_DATA encryptionKeyOut` + - `TPM2B_PRIVATE duplicate` + - `TPM2B_ENCRYPTED_SECRET outSymSeed` + +## References + + - [TCG TPM Library part 3: Commands, section 18.4](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf) + diff --git a/TPM-Commands/TPM2_Import.md b/TPM-Commands/TPM2_Import.md new file mode 100644 index 0000000..8b60de9 --- /dev/null +++ b/TPM-Commands/TPM2_Import.md @@ -0,0 +1,22 @@ +# `TPM2_Import()` + +`TPM2_Import()` reads a wrapped key produced by +[`TPM2_Duplicate()`](TPM2_Duplicate.md) and outputs a blob that can be +saved and later loaded with [`TPM2_Load()`](TPM2_Load.md). + +## Inputs + + - `TPM2B_DATA encryptionKey` (optional; symmetric key to decrypt with) + - `TPM2B_PUBLIC objectPublic` + - `TPM2B_PRIVATE duplicate` + - `TPM2B_ENCRYPTED_SECRET inSymSeed` + - `TPMT_SYM_DEF_OBJECT+ symmetricAlg` + +## Outputs (success case) + + - `TPM2B_PRIVATE outPrivate` + +## References + + - [TCG TPM Library part 3: Commands, section 13.3](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf) + diff --git a/TPM-Commands/TPM2_Load.md b/TPM-Commands/TPM2_Load.md new file mode 100644 index 0000000..4471633 --- /dev/null +++ b/TPM-Commands/TPM2_Load.md @@ -0,0 +1,19 @@ +# `TPM2_Load()` + +`TPM2_Load()` loads a saved key. + +## Inputs + + - `TPMI_DH_OBJECT parentHandle` + - `TPM2B_PRIVATE inPrivate` + - `TPM2B_PUBLIC inPublic` + +## Outputs (success case) + + - `TPM_HANDLE objectHandle` + - `TPM2B_NAME name` + +## References + + - [TCG TPM Library part 3: Commands, section 12.2.2](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf) + diff --git a/Attestation/TPM2_MakeCredential.md b/TPM-Commands/TPM2_MakeCredential.md similarity index 100% rename from Attestation/TPM2_MakeCredential.md rename to TPM-Commands/TPM2_MakeCredential.md diff --git a/Attestation/TPM2_Quote.md b/TPM-Commands/TPM2_Quote.md similarity index 100% rename from Attestation/TPM2_Quote.md rename to TPM-Commands/TPM2_Quote.md