mirror of
https://github.com/tpm2dev/tpm.dev.tutorials.git
synced 2024-11-10 01:12:10 +00:00
Merge pull request #19 from nicowilliams/master
Add text about proving authValues; add text about securing comms with TPMs
This commit is contained in:
commit
0d4368e21c
5 changed files with 228 additions and 9 deletions
|
@ -856,6 +856,15 @@ session.
|
||||||
> sessions as inputs to any TPM command (some TPM commands have no input
|
> sessions as inputs to any TPM command (some TPM commands have no input
|
||||||
> handle parameters, some have one, and some have two).
|
> 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
|
## Restricted Cryptographic Keys
|
||||||
|
|
||||||
Cryptographic keys can either be unrestricted or restricted.
|
Cryptographic keys can either be unrestricted or restricted.
|
||||||
|
|
48
TPM-Commands/TPM2_PolicySecret.md
Normal file
48
TPM-Commands/TPM2_PolicySecret.md
Normal file
|
@ -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)
|
||||||
|
|
82
TPM-Commands/TPM2_PolicySigned.md
Normal file
82
TPM-Commands/TPM2_PolicySigned.md
Normal file
|
@ -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)
|
||||||
|
|
32
TPM-Commands/TPM2_PolicyTicket.md
Normal file
32
TPM-Commands/TPM2_PolicyTicket.md
Normal file
|
@ -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)
|
||||||
|
|
|
@ -3,16 +3,27 @@
|
||||||
This command starts a session that can be used for authorization and/or
|
This command starts a session that can be used for authorization and/or
|
||||||
encryption.
|
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
|
## Inputs
|
||||||
|
|
||||||
- `TPMI_DH_OBJECT+ tpmKey`
|
- `TPMI_DH_OBJECT+ tpmKey`
|
||||||
|
|
||||||
This optional _input_ parameter specifies the handle of a loaded RSA
|
This optional _input_ parameter specifies the handle of a loaded key
|
||||||
decryption key or of a loaded ECDH 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`
|
- `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.
|
`authValue` will be used in the session key computation.
|
||||||
|
|
||||||
- `TPM2B_NONCE nonceCaller`
|
- `TPM2B_NONCE nonceCaller`
|
||||||
|
@ -21,8 +32,8 @@ encryption.
|
||||||
|
|
||||||
- `TPM2B_ENCRYPTED_SECRET encryptedSalt`
|
- `TPM2B_ENCRYPTED_SECRET encryptedSalt`
|
||||||
|
|
||||||
This optional _input_ parameter must be present if `tpmKey` is
|
This optional _input_ parameter is a key exchange message that must
|
||||||
present.
|
be present if `tpmKey` is present.
|
||||||
|
|
||||||
If `tpmKey` is an RSA decryption key then `encryptedSalt` must be an
|
If `tpmKey` is an RSA decryption key then `encryptedSalt` must be an
|
||||||
RSA OEAP ciphertext that will be decrypted with the `tpmKey`. The
|
RSA OEAP ciphertext that will be decrypted with the `tpmKey`. The
|
||||||
|
@ -33,7 +44,12 @@ encryption.
|
||||||
symmetric AES-CFB encryption keys will be derived.
|
symmetric AES-CFB encryption keys will be derived.
|
||||||
|
|
||||||
- `TPM_SE sessionType`
|
- `TPM_SE sessionType`
|
||||||
|
|
||||||
- `TPMT_SYM_DEF+ symmetric`
|
- `TPMT_SYM_DEF+ symmetric`
|
||||||
|
|
||||||
|
The algorithm and key size for command and response parameter
|
||||||
|
encryption.
|
||||||
|
|
||||||
- `TPMI_ALG_HASH authHash`
|
- `TPMI_ALG_HASH authHash`
|
||||||
|
|
||||||
A hash algorithm for the key derivation function.
|
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_POLICY`
|
||||||
- `TPM_SE_TRIAL`
|
- `TPM_SE_TRIAL`
|
||||||
|
|
||||||
### HMAC Sessions
|
## HMAC Sessions
|
||||||
|
|
||||||
If the session is to be an HMAC session authenticating knowledge of some
|
If the session is to be an HMAC session authenticating knowledge of some
|
||||||
entity's `authValue`, then the `bind` argument must be provided.
|
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
|
For policy sessions, the caller should now call one or more
|
||||||
`TPM2_Policy*()` commands to execute the policy identified by the
|
`TPM2_Policy*()` commands to execute the policy identified by the
|
||||||
`authPolicy` value of the entity to be accessed via this session.
|
`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
|
For trial sessions, the caller should now call one or more
|
||||||
`TPM2_Policy*()` commands as will be used in future actual policy
|
`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
|
session after the last policy command -- that will be a value
|
||||||
suitablefor use as an `authPolicy` value for TPM entities.
|
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
|
> 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
|
> 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
|
> that can be used to satisfy HMAC-based authorization for specific
|
||||||
> objects. We will not cover this in detail here.
|
> 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
|
## 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)
|
- [TCG TPM Library part 1: Architecture, sections 18.6, 19, and 21](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture.pdf)
|
||||||
|
|
Loading…
Reference in a new issue