fmaury/tpm.dev.tutorials
1
0
Fork 0
mirror of https://github.com/tpm2dev/tpm.dev.tutorials.git synced 2024-11-24 06:42:11 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge pull request #19 from nicowilliams/master

Browse source 
Add text about proving authValues; add text about securing comms with TPMs
This commit is contained in:
Dimitar Tomov 2022-02-28 18:42:06 +02:00 committed by GitHub
commit 0d4368e21c
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
5 changed files with 228 additions and 9 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
Intro/README.md
View file

@ -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.

48
TPM-Commands/TPM2_PolicySecret.md Normal file
View 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
View 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
View 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)

66
TPM-Commands/TPM2_StartAuthSession.md
View file

@ -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)