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

Expand on restricted keys; describe more TPM commands

Browse source
This commit is contained in:
Nicolas Williams 2021-05-19 16:15:27 -05:00
parent b141291aa2
commit 3b4191c0ae
9 changed files with 164 additions and 43 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

34
Attestation/README.md
View file

@ -95,10 +95,10 @@ key) encrypted to the EKpub and then the attestation client demonstrate
that it was able to decrypt that with the EK. However, this is not
_quite_ how attestation protocols work! Instead of plain asymmetric
encryption the server will use
[`TPM2_MakeCredential()`](TPM2_MakeCredential.md), while the attestation
client will use
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) instead of
plain asymmetric decryption.
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md), while
the attestation client will use
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
instead of plain asymmetric decryption.
## Trusted State Attestation
@ -114,15 +114,15 @@ Typically the attestation protocol will have the client generate a
signing-only asymmetric public key pair known as the attestation key
(AK) with which to sign the PCR quote and eventlog. Binding of the
EKpub and AKpub will happen via
[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) /
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md).
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md).
Note that the [`TPM2_Quote()`](TPM2_Quote.md) function produces a signed
Note that the [`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md) function produces a signed
message -- signed with a TPM-resident AK named by the caller (and to
which they have access), which would be the AK used in the attestation
protocol.
The output of [`TPM2_Quote()`](TPM2_Quote.md) might be the only part of
The output of [`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md) might be the only part of
a client's messages to the attestation service that include a signature
made with the AK, but integrity protection of everything else can be
implied (e.g., the eventlog and PCR values are used to reconstruct the
@ -140,14 +140,14 @@ digest of the selected PCRs. `TPM2_Quote()` signs all of:
## Binding of Other Keys to EKpub
The semantics of [`TPM2_MakeCredential()`](TPM2_MakeCredential.md) /
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) make it
The semantics of [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) make it
possible to bind a TPM-resident object to the TPM's EKpub.
[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) encrypts to the EKpub
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) encrypts to the EKpub
a small secret datum and the name (digest of public part) of the
TPM-resident object being bound. The counter-part to this,
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md), will decrypt
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md), will decrypt
that and return the secret to the application IFF (if and only if) the
caller has access to the named object.
@ -195,14 +195,14 @@ Let's start with few observations and security considerations:
timestamps.
- Replay protection of server to client responses is mostly either not
needed or implicitly provided by [`TPM2_MakeCredential()`](TMP2_MakeCredential.md)
needed or implicitly provided by [`TPM2_MakeCredential()`](TPM2_MakeCredential.md)
because `TPM2_MakeCredential()` generates a secret seed that
randomizes its outputs even when all the inputs are the same across
multiple calls to it.
- Ultimately the protocol *must* make use of
[`TPM2_MakeCredential()`](TMP2_MakeCredential.md) and
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) in order to
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) in order to
authenticate a TPM-running host via its TPM's EKpub.
- Privacy protection of client identifiers may be needed, in which case
@ -288,7 +288,7 @@ protocol:
![Protocol Diagram](Protocol-Two-Messages.png)
(In this diagram we show the use of a TPM simulator on the server side
for implementing [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).)
for implementing [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).)
The server will validate that the `timestamp` is near the current time,
the EKcert (if provided, else the EKpub), the signature using the
@ -340,7 +340,7 @@ desirable anyways for monitoring and alerting purposes.
![Protocol Diagram](Protocol-Three-Messages.png)
(In this diagram we show the use of a TPM simulator on the server side
for implementing [`TPM2_MakeCredential()`](TPM2_MakeCredential.md).)
for implementing [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).)
NOTE well that in this protocol, like single round trip attestation
protocols using only decrypt-only EKs, it is *essential* that the AKcert

86
Intro/README.md
View file

@ -291,16 +291,18 @@ necessarily yields a new name.
> restricted keys. Still, it may be useful to illustrate cryptographic
> object naming with one particularly important use of it.
A pair of functions, `TPM2_MakeCredential()` and
`TPM2_ActivateCredential()`, illustrate the use of cryptographic object
naming as a binding or a sort of authorization function.
A pair of functions,
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md),
illustrate the use of cryptographic object naming as a binding or a sort
of authorization function.
`TPM2_MakeCredential()` can be used to encrypt a datum (a "credential")
to a target TPM such that the target will _only be willing to decrypt
it_ if *and only if* the application calling `TPM2_ActivateCredential()`
to decrypt that credential has access to some key named by the sender,
and that name is a cryptographic name that the sender can and must
compute for itself.
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) can be
used to encrypt a datum (a "credential") to a target TPM such that the
target will _only be willing to decrypt it_ if *and only if* the
application calling `TPM2_ActivateCredential()` to decrypt that
credential has access to some key named by the sender, and that name is
a cryptographic name that the sender can and must compute for itself.
The semantics of these two functions can be used to defeat a
cut-and-paste attack in attestation protocols.
@ -312,21 +314,21 @@ keys, each with zero, one, or more children keys:
```
seed
|
|
v
/|\
/ | \
v v v
primary key (asymmetric encryption)
|
|
v
/|\
/ | \
v v v
secondary keys (of any kind)
|
|
v
/|\
/ | \
v v v
...
```
Note that every key has a parent or is a primary key.
Keys that have no parent are primary keys.
There are four built-in hierarchies:
@ -540,21 +542,53 @@ Cryptographic keys can either be unrestricted or restricted.
An unrestricted signing key can be used to sign arbitrary content.
An unrestricted decryption key can be used to decrypt arbitrary
ciphertexts encrypted to that key's public key.
> NOTE WELL: The endorsement key (EK) is a restricted key.
### Restricted Signing Keys
A restricted signing key can be used to sign only TPM-generated content
as part of specific TPM restricted signing commands. Such content
always begins with a magic byte sequence. Conversely, the TPM refuses
to sign externally generated content that starts with that magic byte
sequence.
sequence. See the [`TPM2_Certify()`](/TPM-Commands/TPM2_Certify.md),
[`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md), `TPM2_CertifyCreation()`,
`TPM2_GetSessionAuditDigest()`, and `TPM2_GetCommandAuditDigest()` TPM
commands.
There is also a notion of signing keys that can only be used to sign
PKIX certificates using `TPM2_CertifyX509()`.
### Restricted Decryption Keys
> NOTE WELL: The endorsement key (EK) is a restricted key.
A restricted decryption key can only be used to decrypt ciphertexts
whose plaintexts have a certain structure. In particular these are used
for `TPM2_MakeCredential()`/`TPM2_ActivateCredential()` 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 ("credentials") to TPMs.
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
("credentials") to TPMs.
There is also a notion of signing keys that can only be used to sign
PKIX certificates.
Another operation that a restricted decryption key can perform is
[`TPM2_Import()`](/TPM-Commands/TPM2_Import.md), which decrypts a key
wrapped to the given decrypt-only key and outputs a file that can be
loaded with [`TPM2_Load()`](/TPM-Commands/TPM2_Load.md). The wrapped
key payload given to [`TPM2_Import()`](/TPM-Commands/TPM2_Import.md) too
has a particular structure and is produced by a remote peer using
[`TPM2_Duplicate()`](/TPM-Commands/TPM2_Duplicate.md).
To recap, a restricted decryption key can only be used to:
- "activate credentials" (made with
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md))
- receive wrapped keys sent by a peer (made with
[`TPM2_Duplicate()`](/TPM-Commands/TPM2_Duplicate.md))
## Attestation

0
Attestation/TPM2_ActivateCredential.md → TPM-Commands/TPM2_ActivateCredential.md
View file

21
TPM-Commands/TPM2_Certify.md Normal file
View file

@ -0,0 +1,21 @@
# `TPM2_Certify()`
`TPM2_Certify()` signs an assertion that some named object is loaded in
the TPM.
## Inputs
- `TPMI_DH_OBJECT objectHandle` (object to be certified)
- `TPMI_DH_OBJECT signHandle` (handle for a signing key)
- `TPM2B_DATA qualifyingData` (extra data)
- `TPMT_SIG_SCHEME inScheme` ("signing scheme to use if the schemefor signHandleis `TPM_ALG_NULL`")
## Outputs (success case)
- `TPM2B_ATTEST certifyInfo` (what was signed)
- `TPMT_SIGNATURE signature` (signature)
## References
- [TCG TPM Library part 3: Commands, section 18.2](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)

25
TPM-Commands/TPM2_Duplicate.md Normal file
View file

@ -0,0 +1,25 @@
# `TPM2_Duplicate()`
`TPM2_Duplicate()` wraps a key, typically encrypting it to a public key
for a key on a remote TPM.
I.e., this is used to export a wrapped key for some target, typically a
remote TPM.
## Inputs
- `TPMI_DH_OBJECT objectHandle` (handle for key to encrypt with)
- `TPMI_DH_OBJECT newParentHandle` (optional; handle for key to wrap to -- "Only the public area of newParentHandle is required to be loaded")
- `TPM2B_DATA encryptionKeyIn` (optional; symmetric key to encrypt with)
- `TPMT_SYM_DEF_OBJECT+ symmetricAlg` ("definition for the symmetric algorithm to be used for the inner wrapper")
## Outputs (success case)
- `TPM2B_DATA encryptionKeyOut`
- `TPM2B_PRIVATE duplicate`
- `TPM2B_ENCRYPTED_SECRET outSymSeed`
## References
- [TCG TPM Library part 3: Commands, section 18.4](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)

22
TPM-Commands/TPM2_Import.md Normal file
View file

@ -0,0 +1,22 @@
# `TPM2_Import()`
`TPM2_Import()` reads a wrapped key produced by
[`TPM2_Duplicate()`](TPM2_Duplicate.md) and outputs a blob that can be
saved and later loaded with [`TPM2_Load()`](TPM2_Load.md).
## Inputs
- `TPM2B_DATA encryptionKey` (optional; symmetric key to decrypt with)
- `TPM2B_PUBLIC objectPublic`
- `TPM2B_PRIVATE duplicate`
- `TPM2B_ENCRYPTED_SECRET inSymSeed`
- `TPMT_SYM_DEF_OBJECT+ symmetricAlg`
## Outputs (success case)
- `TPM2B_PRIVATE outPrivate`
## References
- [TCG TPM Library part 3: Commands, section 13.3](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)

19
TPM-Commands/TPM2_Load.md Normal file
View file

@ -0,0 +1,19 @@
# `TPM2_Load()`
`TPM2_Load()` loads a saved key.
## Inputs
- `TPMI_DH_OBJECT parentHandle`
- `TPM2B_PRIVATE inPrivate`
- `TPM2B_PUBLIC inPublic`
## Outputs (success case)
- `TPM_HANDLE objectHandle`
- `TPM2B_NAME name`
## References
- [TCG TPM Library part 3: Commands, section 12.2.2](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)

0
Attestation/TPM2_MakeCredential.md → TPM-Commands/TPM2_MakeCredential.md
View file

0
Attestation/TPM2_Quote.md → TPM-Commands/TPM2_Quote.md
View file