diff --git a/Intro/README.md b/Intro/README.md index 1419831..33aee7f 100644 --- a/Intro/README.md +++ b/Intro/README.md @@ -856,6 +856,15 @@ session. > sessions as inputs to any TPM command (some TPM commands have no input > handle parameters, some have one, and some have two). +### Proving Knowledge of a Shared `authValue` + +Each session used in a command can prove the caller's (and TPM's) +knowledge of the session's `bind` object's `authValue`. As well, the +`TPM2_PolicySecret()` command can be used to inject the `authValue` of +arbitrary objects into the session's state computations, once again +having the caller prove its knowledge of the `authValue`, and the TPM +will prove its knowledge of it back to the caller on its response. + ## Restricted Cryptographic Keys Cryptographic keys can either be unrestricted or restricted. diff --git a/TPM-Commands/TPM2_PolicySecret.md b/TPM-Commands/TPM2_PolicySecret.md new file mode 100644 index 0000000..4fc38fc --- /dev/null +++ b/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) + diff --git a/TPM-Commands/TPM2_PolicySigned.md b/TPM-Commands/TPM2_PolicySigned.md new file mode 100644 index 0000000..e331dbe --- /dev/null +++ b/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) + diff --git a/TPM-Commands/TPM2_PolicyTicket.md b/TPM-Commands/TPM2_PolicyTicket.md new file mode 100644 index 0000000..a35e407 --- /dev/null +++ b/TPM-Commands/TPM2_PolicyTicket.md @@ -0,0 +1,32 @@ +# `TPM2_PolicyTicket()` + +`TPM2_PolicyTicket()` is very similar to +[`TPM2_PolicySigned()`](TPM2_PolicySigned.md), except that a +TPM-produced ticket is used instead of a signature made by some entity, +and the TPM acts as though the [`TPM2_PolicySigned()`](TPM2_PolicySigned.md) +or [`TPM2_PolicySecret()`](TPM2_PolicySecret.md) command used to produce +the ticket had been executed instead of `TPM2_PolicyTicket()`. + +This is useful for avoiding excessive interactions with a user in a +short period of time. E.g., prompting the user at most once every so +many minutes for: + + - a password, + - smartcard PIN entry, + - and/or biometrics identification. + +## Inputs + + - `TPMI_SH_POLICY policySession` (handle to the session being extended) + - `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) + - `TPM2B_NAME authName` (the name of the object used in the `TPM2_PolicySigned()` or `TPM2_PolicySecret()` command that produced the `ticket`) + - `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_TK_AUTH ticket` (the ticket) + +## 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) + diff --git a/TPM-Commands/TPM2_StartAuthSession.md b/TPM-Commands/TPM2_StartAuthSession.md index 62e0cec..02f3cfe 100644 --- a/TPM-Commands/TPM2_StartAuthSession.md +++ b/TPM-Commands/TPM2_StartAuthSession.md @@ -3,16 +3,27 @@ This command starts a session that can be used for authorization and/or encryption. +Recall that every command can have one or more input sessions. One +session may provide keying for encryption of the first `TPM22B_*` +command parameter and/or response parameter. Every entity that requires +authorization also requires an authorization session handle. + +Every session has state that gets updated with every command, such as +keying material, nonces, etc. + ## Inputs - `TPMI_DH_OBJECT+ tpmKey` - This optional _input_ parameter specifies the handle of a loaded RSA - decryption key or of a loaded ECDH key. + This optional _input_ parameter specifies the handle of a loaded key + object to be used for key exchanged with the TPM. The `tpmKey` must + be an RSA decryption key (in which case RSA key transport will be + used for key exchange) or a ECDH key (in which case ECDH key + agreement will be used for key exchange). - `TPMI_DH_ENTITY+ bind` - This parameter, if not null, references a loaded entity whose + This optional parameter, if given, references a loaded entity whose `authValue` will be used in the session key computation. - `TPM2B_NONCE nonceCaller` @@ -21,8 +32,8 @@ encryption. - `TPM2B_ENCRYPTED_SECRET encryptedSalt` - This optional _input_ parameter must be present if `tpmKey` is - present. + This optional _input_ parameter is a key exchange message that must + be present if `tpmKey` is present. If `tpmKey` is an RSA decryption key then `encryptedSalt` must be an RSA OEAP ciphertext that will be decrypted with the `tpmKey`. The @@ -33,7 +44,12 @@ encryption. symmetric AES-CFB encryption keys will be derived. - `TPM_SE sessionType` + - `TPMT_SYM_DEF+ symmetric` + + The algorithm and key size for command and response parameter + encryption. + - `TPMI_ALG_HASH authHash` A hash algorithm for the key derivation function. @@ -54,18 +70,22 @@ The `sessionType` input parameter must be one of: - `TPM_SE_POLICY` - `TPM_SE_TRIAL` -### HMAC Sessions +## HMAC Sessions If the session is to be an HMAC session authenticating knowledge of some entity's `authValue`, then the `bind` argument must be provided. -### Authorization Sessions +Note that the `TPM2_PolicySecret()` command can reference another entity +whose `authValue` will be used to update the the session's keys. This +way the caller can prove knowledge of arbitrarily many `authValues`. + +## Authorization Sessions For policy sessions, the caller should now call one or more `TPM2_Policy*()` commands to execute the policy identified by the `authPolicy` value of the entity to be accessed via this session. -### Trial Policies +## Trial Policies For trial sessions, the caller should now call one or more `TPM2_Policy*()` commands as will be used in future actual policy @@ -73,7 +93,7 @@ sessions, then extract the `policyDigest` of the session after the last policy command -- that will be a value suitablefor use as an `authPolicy` value for TPM entities. -### Encryption Sessions +## Encryption Sessions > All sessions can be used for encryption that were created with either > or both of the `bind` input parameter and the pair of input parameters @@ -145,6 +165,34 @@ that itself used the EK as its `tpmKey` input. > that can be used to satisfy HMAC-based authorization for specific > objects. We will not cover this in detail here. +## Establishing Trust in a TPM + +Given a computer that has a discrete TPM, how does software running on +that computer establish trust in the dTPM? + +This is an important question since failure to do this will render the +computer vulnerable to [certain attacks](https://dolosgroup.io/blog/2021/7/9/from-stolen-laptop-to-inside-the-company-network) +on it. + +Use of encryption sessions is a must. These must be keyed by using a +key exchange with a public key of the dTPM's that is accessible to the +caller. For example, the dTPM's `EKpub`, or any key object with the +`decrypt`, `fixedTPM`, and `fixedParent` attributes, but not the +`stClear` attribute, and preferably a primary. The caller must reliably +remember this public key as early as possible. The caller must also +validate the dTPM's `EKcert` as early as possible (especially before the +endorsement hierarchy is made unavailable). + +Unless the caller has a priori knowledge of that public key for the dTPM +prior to the first time the caller speaks to the dTPM, then the caller +will be vulnerable to the dTPM being replaced. + +In an ideal world the BIOS would store this public key in protected +(((E)E)P)ROM, the BIOS would always use encrypted sessions for RTM, and +the BIOS would make this public key available to applications that wish +to use the dTPM. Where this is not available, online attestation +protocols can serve to furnish or confirm this key to the application. + ## References - [TCG TPM Library part 1: Architecture, sections 18.6, 19, and 21](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture.pdf)