Expand on TPM2_{Make,Activate}Credential

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()`)
 

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)