Expand on TPM2_{Make,Activate}Credential

This commit is contained in:
Nicolas Williams 2021-06-03 18:26:55 -05:00
parent 3017b7eae9
commit 4d8b1e90a0
2 changed files with 120 additions and 17 deletions

View file

@ -1,20 +1,65 @@
# `TPM2_ActivateCredential()` # `TPM2_ActivateCredential()`
`TPM2_ActivateCredential()` decrypts a ciphertext made by `TPM2_ActivateCredential()` is the flip side to
[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) and checks that the [`TPM2_MakeCredential()`](TPM2_MakeCredential.md), decrypting a small
caller has access to the object named by the caller of ciphertext made by [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).
[`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.
Together with [`TPM2_MakeCredential()`](TPM2_MakeCredential.md), The intersting things about `TPM2_ActivateCredential()` are that
this function can be used to implement attestation protocols.
- 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 ## 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 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_ID_OBJECT credentialBlob` (output of `TPM2_MakeCredential()`)
- `TPM2B_ENCRYPTED_SECRET secret` (output of `TPM2_MakeCredential()`) - `TPM2B_ENCRYPTED_SECRET secret` (output of `TPM2_MakeCredential()`)

View file

@ -1,19 +1,77 @@
# `TPM2_MakeCredential()` # `TPM2_MakeCredential()`
`TPM2_MakeCredential()` takes an EKpub, the name of an object in a TPM `TPM2_MakeCredential()` and
identified by that EKpub, and a small secret, and it encrypts `{name, [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) provide a
secret}` to the EKpub. 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 semantics are on the
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) side. [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) side.
Together with [`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md), Together with [`TPM2_Quote()`](TPM2_Quote.md) and
this function can be used to implement attestation protocols. [`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 ## 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_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) - `TPM2B_NAME objectName` (name of object resident on the same TPM as `handle` that `TPM2_ActivateCredential()` will check)