diff --git a/TPM-Commands/TPM2_ActivateCredential.md b/TPM-Commands/TPM2_ActivateCredential.md index 6f4251d..3704fed 100644 --- a/TPM-Commands/TPM2_ActivateCredential.md +++ b/TPM-Commands/TPM2_ActivateCredential.md @@ -1,20 +1,65 @@ # `TPM2_ActivateCredential()` -`TPM2_ActivateCredential()` decrypts a ciphertext made by -[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) and checks that the -caller has access to the object named by the caller of -[`TPM2_MakeCredential()`](TPM2_MakeCredential.md), and if so then -`TPM2_ActivateCredential()` outputs the small secret provided by the -caller of [`TPM2_MakeCredential()`](TPM2_MakeCredential.md), -otherwise `TPM2_ActivateCredential()` fails. +`TPM2_ActivateCredential()` is the flip side to +[`TPM2_MakeCredential()`](TPM2_MakeCredential.md), decrypting a small +ciphertext made by [`TPM2_MakeCredential()`](TPM2_MakeCredential.md). -Together with [`TPM2_MakeCredential()`](TPM2_MakeCredential.md), -this function can be used to implement attestation protocols. +The intersting things about `TPM2_ActivateCredential()` are that + + - the decryption key used may be a restricted key (which + `TPM2_RSA_Decrypt()` would refuse to use) + - and that `TPM2_ActivateCredential()` evaluates an authorization + policy of the sender's choice. + +Together with [`TPM2_MakeCredential()`](TPM2_MakeCredential.md) an +[`TPM2_Quote()`](TPM2_Quote.md) this function can be used to implement +attestation protocols. + +Two of the input parameters of `TPM2_ActivateCredential()`, `keyHandle` +and `activateHandle`, correspond to the `handle` and `objectName` inputs +of [`TPM2_MakeCredential()`](TPM2_MakeCredential.md), respectively. The +other inputs are [`TPM2_MakeCredential()`](TPM2_MakeCredential.md)'s +outputs. The output, `certInfo` is +[`TPM2_MakeCredential()`](TPM2_MakeCredential.md)'s `credential` input. + +## Authorization + +`TPM2_ActivateCredential()` checks the authorization of the caller to +perform this operation by enforcing the `keyHandle`'s policy in the +`USER` role, and the `activateHandle`'s policy in the `ADMIN` role. See +section 19.2 of [TCG TPM Library part 1: +Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf). + +What this means specifically depends on whether the `userWithAuth` +attribute is set on the `keyHandle` and whether the `adminWithPolicy` +attribute is set on the `activateHandle`. + +In particular, if `adminWithPolicy` is set on the `activateHandle` then +the authorization session's `policyDigest` must match the +`activateHandle`'s policy _and_ the authorization session's +`commandCode` must be set to `TPM_CC_ActivateCredential`, which means +that the caller must have called `TPM2_PolicyCommandCode()` with +`TPM_CC_ActivateCredential` as the command code argument. + +Some possible authorization policies to enforce include: + + - that some non-resettable PCR has not been extended since boot + + This allows the recipient to extend that PCR immediately after + activating the credential to prevent the attestation protocol from + being used again without rebooting. + + - user authentication / attended boot + + The policy could require physical presence, authentication of a user + with biometrics and/or a smartcard and/or a password. + + - locality ## Inputs - - `TPMI_DH_OBJECT activateHandle` (e.g., handle for an AK) - `TPMI_DH_OBJECT keyHandle` (e.g., handle for an EK corresponding to the EKpub encrypted to by `TPM2_MakeCredential()`) + - `TPMI_DH_OBJECT activateHandle` (e.g., handle for an AK) - `TPM2B_ID_OBJECT credentialBlob` (output of `TPM2_MakeCredential()`) - `TPM2B_ENCRYPTED_SECRET secret` (output of `TPM2_MakeCredential()`) diff --git a/TPM-Commands/TPM2_MakeCredential.md b/TPM-Commands/TPM2_MakeCredential.md index d279e29..664709d 100644 --- a/TPM-Commands/TPM2_MakeCredential.md +++ b/TPM-Commands/TPM2_MakeCredential.md @@ -1,19 +1,77 @@ # `TPM2_MakeCredential()` -`TPM2_MakeCredential()` takes an EKpub, the name of an object in a TPM -identified by that EKpub, and a small secret, and it encrypts `{name, -secret}` to the EKpub. +`TPM2_MakeCredential()` and +[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) provide a +mechanism by which an application can send secrets to a TPM-using +application. This mechanism is asymmetric encryption/decryption with +support for an authorization policy of the sender's choice. -Nothing terribly interesting happens here. All the interesting +`TPM2_MakeCredential()` takes an a public key (typically the endorsement +key's public key), the [cryptographic name of an +object](/Intro/README.md#Cryptographic-Object-Naming) in a TPM +identified by that the given public key, and a small secret called a +`credential`, and it encrypts `{name, credential}` to the given public +key. + +The object name input parameter, being a name, binds an optional +authorization policy that +[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) will enforce. + +`TPM2_MakeCredential()` can be implemented entirely in software, as it +uses no secret, TPM-resident key material. All the interesting semantics are on the [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) side. -Together with [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md), -this function can be used to implement attestation protocols. +Together with [`TPM2_Quote()`](TPM2_Quote.md) and +[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md), this function +can be used to implement attestation protocols. + +A typical use is to encrypt an AES key to an `EKpub`, then encrypt a +large secret payload in the AES key, then sending the outputs of +`TPM2_MakeCredential()` and the encrypted large secret payload. The +peer receives these items and calls +[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) to recover the +AES key, then decrypts the large ciphertext payload to recover the large +cleartext secret. + +> NOTE: The `objectName` input names a key object that must present on +> the destination TPM, and the `objectName` is included in the plaintext +> that is encrypted to the public key identified by `handle`, _but_ none +> of the key material of `objectName` is used to key any cryptographic +> operations in `TPM2_MakeCredential()`, and therefore neither is the +> private area of `objectName` on the destination TPM used in any +> cryptographic operations in +> [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md). +> +> This means that the key named by `objectName` can even be a +> universally-well-known key. The only part of that key that truly +> matters is the policy digest named in the public area of `objectName`. + +## Authorization + +[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) checks the +authorization of the caller to perform this operation by enforcing the +sender's policy named by the sender's `objectName`. See +[here](TPM2_ActivateCredential.md) for details. + +Some possible authorization policies to enforce include: + + - that some non-resettable PCR has not been extended since boot + + This allows the recipient to extend that PCR immediately after + activating the credential to prevent the attestation protocol from + being used again without rebooting. + + - user authentication / attended boot + + The policy could require physical presence, authentication of a user + with biometrics and/or a smartcard and/or a password. + + - locality ## Inputs - - `TPMI_DH_OBJECT handle` (e.g., an EKpub to encrypt to) + - `TPMI_DH_OBJECT handle` (public key to encrypt to, typically a remote TPM's EKpub) - `TPM2B_DIGEST credential` (not necessarily a digest, but a small [digest-sized] secret) - `TPM2B_NAME objectName` (name of object resident on the same TPM as `handle` that `TPM2_ActivateCredential()` will check)