tpm.dev.tutorials/TPM-Commands/TPM2_MakeCredential.md

TPM2_MakeCredential()

TPM2_MakeCredential() and TPM2_ActivateCredential() 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.

TPM2_MakeCredential() takes an a public key (typically the endorsement key's public key), the cryptographic name of an object 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() 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() side.

Together with TPM2_Quote() and TPM2_ActivateCredential(), 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() 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().

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() checks the authorization of the caller to perform this operation by enforcing the sender's policy named by the sender's objectName. See here 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 (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)

Outputs

• TPM2B_ID_OBJECT credentialBlob (ciphertext of encryption of credential with a secret "seed" [see below])
• TPM2B_ENCRYPTED_SECRET secret (ciphertext of encryption of a "seed" to handle)

References

• TCG TPM Library part 1: Architecture, section 24
• TCG TPM Library part 2: Structures
• TCG TPM Library part 3: Commands, section 13
• TCG TPM Library part 3: Commands Code, section 13