fmaury/tpm.dev.tutorials
1
0
Fork 0
mirror of https://github.com/tpm2dev/tpm.dev.tutorials.git synced 2025-05-17 20:43:51 +00:00
Code Issues Projects Releases Packages Wiki Activity

Merge branch 'master' into ian2

Browse source
This commit is contained in:
Ian 2022-02-28 20:52:58 +02:00 • committed by GitHub
commit 93f931026e
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
7 changed files with 232 additions and 36 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
Attestation/README.md
View file

@ -305,7 +305,7 @@ Let's start with few observations and security considerations:
> on signing quotes. Essentially one can simply send an unsigned
> reading of the client's TPM's PCRs and clock information and use an
> activation object with `adminWithPolicy` set and a `policyDigest`
> of a policy that uses the `TPM2_PolicyCounterTimer() and
> of a policy that uses the `TPM2_PolicyCounterTimer()` and
> `TPM2_PolicyPCR()` commands to enforce that the `resetCount` and
> the PCRs are as asserted in the protocol. The server can then
> construct the same policy to compute the name of the activation

15
Intro/README.md
View file

@ -381,15 +381,15 @@ used to authenticate the TPM's legitimacy. The EK's public key
("EKpub") can be used to uniquely identify a TPM, and possibly link to
the platform's, and even the platform's user(s)' identities.
The [`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) command creates
The [`TPM2_CreatePrimary()`](/TPM-Commands/TPM2_CreatePrimary.md) command creates
primary key objects deterministically from the hierarchy's seed and the
"template" used to create the key (which includes a "unique" area that
provides "entropy" to the key derivation function).
The [`TPM2_Create()`](TPM2_Create.md) command creates a ordinary
The [`TPM2_Create()`](/TPM-Commands/TPM2_Create.md) command creates a ordinary
objects.
The [`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md) command can also
The [`TPM2_CreateLoaded()`](/TPM-Commands/TPM2_CreateLoaded.md) command can also
create primary key objects deterministically from the hierarchy's seed
and the "template" used to create the key (which includes a "unique"
area that provides "entropy" to the key derivation function).
@ -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.

23
PythonExamples/README.md
View file

@ -14,28 +14,5 @@ Each example can be run just by typing `python3 example.py`
Each example has an accompanying description as markdown file, plus annotated code.
<<<<<<< HEAD
* [randomnumber]
* [quote]
## Notes on TCTI Errors
When an `ESAPI` object is created it will print out errors as it searches for a suitable TPM devices. For example:
```bash
~/tpm.dev.tutorials/PythonExamples$ python3 randomnumber.py
ERROR:tcti:src/tss2-tcti/tcti-device.c:442:Tss2_Tcti_Device_Init() Failed to open specified TCTI device file /dev/tpmrm0: No such file or directory
ERROR:tcti:src/tss2-tcti/tctildr-dl.c:154:tcti_from_file() Could not initialize TCTI file: libtss2-tcti-device.so.0
ERROR:tcti:src/tss2-tcti/tcti-device.c:442:Tss2_Tcti_Device_Init() Failed to open specified TCTI device file /dev/tpm0: No such file or directory
ERROR:tcti:src/tss2-tcti/tctildr-dl.c:154:tcti_from_file() Could not initialize TCTI file: libtss2-tcti-device.so.0
ERROR:tcti:src/tss2-tcti/tcti-swtpm.c:222:tcti_control_command() Control command failed with error: 1
ERROR:tcti:src/tss2-tcti/tcti-swtpm.c:330:tcti_swtpm_set_locality() Failed to set locality: 0xa000a
WARNING:tcti:src/tss2-tcti/tcti-swtpm.c:599:Tss2_Tcti_Swtpm_Init() Could not set locality via control channel: 0xa000a
ERROR:tcti:src/tss2-tcti/tctildr-dl.c:154:tcti_from_file() Could not initialize TCTI file: libtss2-tcti-swtpm.so.0
type is <class 'tpm2_pytss.types.TPM2B_DIGEST'>
r is a10ab7558675a56c
as hex 11604288967829464428
```
=======
* [quote](quote.md)
>>>>>>> fee864e50cfe60b9578dc5f6732ed343f0246929

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)