fmaury/tpm.dev.tutorials
1
0
Fork 0
mirror of https://github.com/tpm2dev/tpm.dev.tutorials.git synced 2024-12-26 19:32:10 +00:00
Code Issues Projects Releases Packages Wiki Activity

Intro: Add use cases sections, link more resources

Browse source
This commit is contained in:
Nicolas Williams 2021-05-26 17:30:34 -05:00
parent 57cc17c6cb
commit 93af1b4003
1 changed files with 241 additions and 21 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

262
Intro/README.md
View file

@ -48,6 +48,39 @@ general, which include:
> software development using TPMs will want to make use of [TCG
> specifications and other resources](#Other-Resources).
## Use Cases
Here are _some_ use cases that TPMs can be applied to
- off-line root of trust measurement (RTM) to check that a device is
healthy
("off-line" meaning "no network needed")
- encrypted storage
- online RTM to check that a device is healthy and authorize it to have
access to a network
("online" meaning "demonstrate health via networked interaction with
other devices")
- encrypted storage
- hardware security module (HSM)
- certification authority (CA)
- TPMs as smartcards
- authentication and authorization of console and/or remote user logins
- e.g., require biometrics, smartcard, admin credentials, multiple
users' authentication, time-of-day restrictions, etc.
- entropy source (random number generator)
- cryptographic co-processor
## Glossary
> For a glossary, see section 4 of [TCG TPM 2.0 Library part 1:
@ -492,16 +525,36 @@ policy because the TPM knows only a digest of it.
Construction of a policy consists of computing it by hash extending an
initial all-zeroes value with the commands that make up the policy.
This can be done entirely in software, but the TPM supports a notion of
"trial sessions" where the application can issue policy commands to
build up a policy digest without the application having to know how to
do that in software. Trial sessions have every policy command succeed,
but they authorize nothing -- the point of a trial session is only to
compute and extract a `policyDigest` at the end of the policy.
### Policy Evaluation
Evaluation of a policy consists of issuing those same commands to the
TPM in a session, with those commands either evaluated immediately or
deferred to the time of execution of the to-be-authorized command, but
the TPM computes the same hash extension as it goes. Once all policy
commands being evaluated have succeeded, the resulting hash extension
value is compared to the policy that protects the resource(s) being used
by the to-be-authorized command, and if it matches, then the command is
allowed, otherwise it is not.
TPM in a [non-trial] session, with those commands either evaluated
either immediately or deferred to the time of execution of the
to-be-authorized command, but the TPM computes the same hash extension
as it goes. Once all policy commands issued have been evaluated and
have succeeded, the resulting hash extension value is compared to the
policy that protects the resource used by the to-be-authorized command,
and if and only if the digest matches, then the command is allowed,
otherwise it is not.
For example, one might construct a policy like so:
```bash
$ tpm2 flushcontext -t
$ tpm2 flushcontext -s
$ tpm2 startauthsession --session session.ctx --policy-session
$ tpm2 policysecret --session session.ctx --object-context endorsement
$ tpm2 policycommandcode -S session.ctx -L activate.ctx TPM2_CC_ActivateCredential
```
which saves the digest of the policy in a file named `activate.ctx`.
### Indirect Policies
@ -540,9 +593,108 @@ indexes, policies can be used to:
## Sessions
A session is an object (meaning, among other things, that it can be
loaded and unloaded as needed) that represents the current policy
construction or evaluation hash extension digest (the `policyDigest`),
and the objects that have been granted access.
loaded and unloaded as needed) that represents the current state used
for authorization of actions or for encryption of traffic between the
application and the TPM.
There are two types of sessions then: those used for authorization, and
those used for encryption of application `<->` TPM communication.
Authorization sessions contain state such as a `policyDigest`
representing authorization policy that has been satisfied, and various
other state. TPM commands may check that an authorization session's
state satisfies the requirements for use of the argument objects passed
to the commands.
### Authorization Session State
Authorization sessions have a number of state attributes. Some of these
are set at the time of creation of the session. Some of these can be
set directly with `TPM2_Policy*()` commands. Others evolve in other
ways. These state attributes are:
- `policyDigest`
A hash extension digest of all the policy commands sent by the
application in this session thus far. Every successful
`TPM2_Policy*()` command extends this.
Objects may have a policy digest set on them to refer to the policy
that an application must meet in order to use them. The application
has to issue the `TPM2_Policy*()` commands, in order, that produce
that digest, the commands must all succeed, and the `policyDigest`
must equal that of the object.
- `isTrialPolicy`
When this is set then the session will not authorize anything at all
and all policy commands will be assumed to be met and will not be
evaluated. This is useful for constructing and extracting from the
TPM the `policyDigest` of a policy to set on some future new
object(s).
Sessions that have this set are known as "trial sessions".
Applications can construct `policyDigest` values entirely in
software, but using the TPM with a trial session saves one the
bother.
- `commandCode`
Identifies a command that will be authorized by the policy referred
to by `policyDigest`.
If a policy requires this, then it authorizes the one command
identified by the command code.
- `cpHash`
A hash of some command's parameters. If a policy requires this, then
it authorizes the one command whose parameters match this hash.
- `commandLocality`
A locality that the application must be in.
- policy reuse / expiration state:
- `startTime`
The start time of the session.
- `timeout`
The lifetime of the session.
- `nonceTPM`
- Authentication requirements:
- `isAuthValueNeeded`
- `isPasswordNeeded`
- `isPPRequired`
PP == physical presence.
- `checkNvWritten`
- `nvWrittenState`
- `nameHash`
- `pcrUpdateCounter`
### Encryption Sessions
> Work in progress.
Sessions can also be used for encrypting TPM command arguments and
results. This can be useful when one does not trust the path to the
TPM, such as when the TPM is remote.
> TODO: Discuss key exchange options, etc.
## Restricted Cryptographic Keys
@ -579,7 +731,7 @@ for [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
to allow the TPM-using application to get the plaintext if and only if
(IFF) the plaintext cryptographically names an object that the
application has access to. This is used to communicate secrets
application has access to. This is used to remotely communicate secrets
("credentials") to TPMs.
Another operation that a restricted decryption key can perform is
@ -619,19 +771,87 @@ many TPM concepts can be used to great effect:
- authorization of devices onto a network
- etc.
## Use Cases (reprise)
### Off-line RTM / TOTP
Use a TPM to generate a time-based one-time (TOTP) password based on
current time and a seed derived from selected PCR values, then display
this TOTP. A user can then check that the TOTP presented by the device
matches the TOTP on a separate authenticator.
Links:
- https://github.com/tpm2-software/tpm2-totp
- https://github.com/mjg59/tpmtotp
- https://trmm.net/Tpmtotp/
### Online RTM (aka Attestation)
See [our tutorial on attestation](/Attestation/README.md).
### Encrypted Storage
- [Safeboot](https://safeboot.dev/)
- [Hacking with a TPM](https://c3media.vsos.ethz.ch/congress/2019/slides-pdf/36c3-10564-hacking_with_a_tpm.pdf)
### HSM / CA / Smartcard
Use `TPM2_Sign()` or `TPM2_CertifyX509()` to sign certificates with a
TPM-resident key that is fixedTPM and fixedParent.
Use `TPM2_GetCommandAuditDigest()` to implement an audit trail for the
CA.
### Authentication and Authorization of Console and/or Remote User Logins
Use [TPM policies](#Authentication-and-Authorization).
### Entropy Source
See our tutorial on [TPM-based RNGs](/Random_Number_Generator/README.md).
### Cryptographic Co-Processor
Use cryptographic primitives provided by the TPM using unrestricted key
objects:
- use TPM cryptographic primitives commands directly -- see
[TCG TPM 2.0 Library part 3: Commands, sections 14 and 15](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)
- use PKCS#11 with a TPM-backed token provider:
- https://github.com/tpm2-software/tpm2-pkcs11
- https://docs.oracle.com/cd/E36784_01/html/E37121/gmsch.html
- https://incenp.org/notes/2020/tpm-based-ssh-key.html
- http://trousers.sourceforge.net/pkcs11.html
- https://www.lorier.net/docs/tpm
- use OpenSSL with a PKCS#11 `ENGINE` (see above)
- use OpenSSL with a TPM `ENGINE`
- https://github.com/tpm2-software/tpm2-tss-engine
# Other Resources
[A Practical Guide to TPM 2.0](https://trustedcomputinggroup.org/resource/a-practical-guide-to-tpm-2-0/)
is an excellent book that informed much of this tutorial.
- [A Practical Guide to TPM 2.0](https://trustedcomputinggroup.org/resource/a-practical-guide-to-tpm-2-0/)
is an excellent book that informed much of this tutorial.
Nokia has a [TPM course](https://github.com/nokia/TPMCourse/tree/master/docs).
- Of course, there is the [TPM.dev community](https://developers.tpm.dev/),
which has many resources, posts, a chat room, and knowledgeable
participants.
The TCG has a number of members-only tutorials, but it seems that it is
possible to be invited to be a non-fee paying member.
- Nokia has a [TPM course](https://github.com/nokia/TPMCourse/tree/master/docs).
Core TCG TPM specs:
- [Hacking with a TPM](https://c3media.vsos.ethz.ch/congress/2019/slides-pdf/36c3-10564-hacking_with_a_tpm.pdf).
- [TCG TPM 2.0 Library part 1: Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf).
- [TCG TPM 2.0 Library part 2: Structures](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part2_Structures_pub.pdf).
- [TCG TPM 2.0 Library part 3: Commands, section 12](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf).
- [TCG TPM 2.0 Library part 3: Commands Code, section 12](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_code_pub.pdf).
- [Microsoft has solid TPM resources](https://docs.microsoft.com/en-us/windows/security/information-protection/tpm/trusted-platform-module-top-node).
- The TCG has a number of members-only tutorials, but it seems that it
is possible to be invited to be a non-fee paying member.
- Core TCG TPM specs:
- [TCG TPM 2.0 Library part 1: Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf).
- [TCG TPM 2.0 Library part 2: Structures](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part2_Structures_pub.pdf).
- [TCG TPM 2.0 Library part 3: Commands](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf).
- [TCG TPM 2.0 Library part 3: Commands Code](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_code_pub.pdf).