Describe TPM2_Policy{Secret,Signed}()

TPM-Commands/TPM2_PolicySecret.md

@@ -0,0 +1,48 @@
+# `TPM2_PolicySecret()`
+
+`TPM2_PolicySecret()` allows a caller to assert and prove knowledge of
+the `authValue` associated with some entity.  The `authValue` affects
+the HMAC calculation for the affected session, so the command will fail
+if the caller does not know the `authValue`.
+
+The `tpmNonce` input strongly binds the command to the `policySession`.
+If the `Empty Buffer` is given as the `tpmNonce`, then the
+`TPM2_PolicySecret()` command could be altered to refer to any other
+policy on the same TPM if the object referred to by `authHandle`
+requires an HMAC or policy session, or any TPM otherwise.
+
+If a `policyTicket` is requested and output, that ticket can be used (up
+to its `expiration`), via `TPM2_PolicyTicket()`, to satisfy the same
+`TPM2_PolicySecret()` that produced the ticket.
+
+That is, a caller can get a ticket from a `TPM2_PolicySecret()`
+invocation that allows it to re-use the `authValue` proof many times
+prior to the ticket's expiration without having to actually prove the
+`authValue` again.  For example, if the `authValue` is obtained from a
+password prompt and the password and `authValue` erased from memory as
+soon as the `TPM2_PolicySecret()` command is marshalled, then the caller
+can keep satisfying policies containing that `TPM2_PolicySecret()` by
+using `TPM2_PolicyTicket()` instead of `TPM2_PolicySecret()`.  This is
+useful to avoid requiring repeated password prompts in a short time
+span.
+
+## Inputs
+
+ - `TPMI_DH_OBJECT authHandle` (handle to the entity whose `authValue` is to be proven)
+ - `TPMI_SH_POLICY policySession` (handle to the session being extended)
+ - `TPM2B_NONCE tpmNonce` (the policy nonce for the `policySession`)
+ - `TPM2B_DIGEST cpHashA` (the command parameter hash of a single command to be authorized, or `Empty Buffer` to not so-limit the assertion)
+ - `TPM2B_NONCE policyRef` (an opaque value of the caller's choosing, possibly the `Empty Buffer`, that is used to extend the `policySession`'s `policyDigest` along with the name of `authHandle`)
+ - `INT32 expiration` (a positive or negative number of milliseconds which, if non-zero, sets an expiration for this assertion; if zero or positive then a `policyTicket` will not be output)
+
+## Outputs
+
+ - `TPM2B_TIMEOUT timeout` (implementation-specific indication of actual timeout for the session)
+ - `TPMT_TK_AUTH policyTicket`
+
+## References
+
+ - [TCG TPM Library part 1: Architecture, section 19.7.12](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf)
+ - [TCG TPM Library part 1: Architecture, section 19.7.15](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf)
+ - [TCG TPM Library part 3: Commands, section 23.4](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
+

TPM-Commands/TPM2_PolicySigned.md

@@ -0,0 +1,82 @@
+# `TPM2_PolicySigned()`
+
+`TPM2_PolicySigned()` allows a caller to provide a signature of some
+assertion, with the signature made by some authorizing entity identified
+by its public key.
+
+The semantics of the signature are arbitrary and up to the entity
+constructing the policies that contain this command.  Possible semantics
+include:
+
+ - biometrics user identification (whereby the biometrics device signs
+   an assertion that a user identified by the opaque value of
+   `policyRef` has been identified biometrically)
+
+ - smartcard-based user authentication (whereby access to a private
+   signing key on a smartcard is used to sign an assertion that the user
+   has been authenticated by the user's possession of the smartcard and
+   interactive PIN entry to unlock it)
+
+ - assertion of attested state being trusted (whereby an attestation
+   server signs such an assertion)
+
+ - etc.
+
+The signature made by the signed is over the following digest:
+
+  `aHash := H(nonceTPM || expiration || cpHashA || policyRef)`
+
+where `H()` is the digest algorithm associated with the authorizing
+entity's public key.
+
+When evaluating this assertion in a policy session, the TPM will check
+that the signature matches the above hash as constructed by the TPM from
+the `TPM2_PolicySigned()` command parameters.
+
+When evaluating this assertion in a trial session, the TPM will ignore
+the signature and will extend the `policySession`'s `policyDigest` as if
+the signature had matched the hash.
+
+The `nonceTPM` input strongly binds the command to the `policySession`.
+If the `Empty Buffer` is given as the `nonceTPM`, then the
+`TPM2_PolicySigned()` command could be altered to refer to any other
+policy any TPM.  For this reason it is important to use the
+`policySession`'s `nonceTPM` in any call to `TPM2_PolicySigned()`.
+
+If a `policyTicket` is requested and output, that ticket can be used (up
+to its `expiration`), via `TPM2_PolicyTicket()`, to satisfy the same
+`TPM2_PolicySigned()` that produced the ticket.
+
+That is, a caller can get a ticket from a `TPM2_PolicySigned()`
+invocation that allows it to re-use the `auth` signature many times
+prior to the ticket's expiration without having to get the authorizing
+entity to re-sign.  For example, if the authorizing entity is a
+biometrics identification device, or a smartcard, then the interactive
+human identification or interactive smartcard PIN entry steps can be
+eschewed by the caller up to the ticket's expiration, using the `ticket`
+(via `TPM2_PolicyTicket()`) instead to satisfy the same
+`TPM2_PolicySigned()` command in any policy on that TPM.  This is useful
+to avoid requiring repeated biometrics or PIN entry in a short time
+span.
+
+## Inputs
+
+ - `TPMI_DH_OBJECT authObject` (handle to the key object whose public key is the signing entity's)
+ - `TPMI_SH_POLICY policySession` (handle to the session being extended)
+ - `TPM2B_NONCE nonceTPM` (the policy nonce for the `policySession`)
+ - `TPM2B_DIGEST cpHashA` (the command parameter hash of a single command to be authorized, or `Empty Buffer` to not so-limit the assertion)
+ - `TPM2B_NONCE policyRef` (an opaque value of the caller's and/or signer's choosing that is used to limit the value of the signature and to extend the `policySession`'s `policyDigest` along with the `authObject`'s name)
+ - `INT32 expiration` (a positive or negative number of milliseconds which, if non-zero, sets an expiration for this assertion; if zero or positive then a `policyTicket` will not be output)
+ - `TPMT_SIGNATURE auth` (the signature; ignored if the `policySession` is a trial session)
+
+## Outputs
+
+ - `TPM2B_TIMEOUT timeout` (implementation-specific indication of actual timeout for the session)
+ - `TPMT_TK_AUTH policyTicket`
+
+## References
+
+ - [TCG TPM Library part 1: Architecture, section 19.7.12](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf)
+ - [TCG TPM Library part 1: Architecture, section 19.7.15](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf)
+ - [TCG TPM Library part 3: Commands, section 23.3](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
+