mirror of
https://github.com/tpm2dev/tpm.dev.tutorials.git
synced 2024-11-10 01:12:10 +00:00
Expand on restricted keys; describe more TPM commands
This commit is contained in:
parent
b141291aa2
commit
3b4191c0ae
9 changed files with 164 additions and 43 deletions
|
@ -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
|
that it was able to decrypt that with the EK. However, this is not
|
||||||
_quite_ how attestation protocols work! Instead of plain asymmetric
|
_quite_ how attestation protocols work! Instead of plain asymmetric
|
||||||
encryption the server will use
|
encryption the server will use
|
||||||
[`TPM2_MakeCredential()`](TPM2_MakeCredential.md), while the attestation
|
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md), while
|
||||||
client will use
|
the attestation client will use
|
||||||
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) instead of
|
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
|
||||||
plain asymmetric decryption.
|
instead of plain asymmetric decryption.
|
||||||
|
|
||||||
## Trusted State Attestation
|
## 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
|
signing-only asymmetric public key pair known as the attestation key
|
||||||
(AK) with which to sign the PCR quote and eventlog. Binding of the
|
(AK) with which to sign the PCR quote and eventlog. Binding of the
|
||||||
EKpub and AKpub will happen via
|
EKpub and AKpub will happen via
|
||||||
[`TPM2_MakeCredential()`](TPM2_MakeCredential.md) /
|
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
|
||||||
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.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
|
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
|
which they have access), which would be the AK used in the attestation
|
||||||
protocol.
|
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
|
a client's messages to the attestation service that include a signature
|
||||||
made with the AK, but integrity protection of everything else can be
|
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
|
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
|
## Binding of Other Keys to EKpub
|
||||||
|
|
||||||
The semantics of [`TPM2_MakeCredential()`](TPM2_MakeCredential.md) /
|
The semantics of [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
|
||||||
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) make it
|
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) make it
|
||||||
possible to bind a TPM-resident object to the TPM's EKpub.
|
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
|
a small secret datum and the name (digest of public part) of the
|
||||||
TPM-resident object being bound. The counter-part to this,
|
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
|
that and return the secret to the application IFF (if and only if) the
|
||||||
caller has access to the named object.
|
caller has access to the named object.
|
||||||
|
|
||||||
|
@ -195,14 +195,14 @@ Let's start with few observations and security considerations:
|
||||||
timestamps.
|
timestamps.
|
||||||
|
|
||||||
- Replay protection of server to client responses is mostly either not
|
- 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
|
because `TPM2_MakeCredential()` generates a secret seed that
|
||||||
randomizes its outputs even when all the inputs are the same across
|
randomizes its outputs even when all the inputs are the same across
|
||||||
multiple calls to it.
|
multiple calls to it.
|
||||||
|
|
||||||
- Ultimately the protocol *must* make use of
|
- Ultimately the protocol *must* make use of
|
||||||
[`TPM2_MakeCredential()`](TMP2_MakeCredential.md) and
|
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
|
||||||
[`TPM2_ActivateCredential()`](TPM2_ActivateCredential.md) in order to
|
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md) in order to
|
||||||
authenticate a TPM-running host via its TPM's EKpub.
|
authenticate a TPM-running host via its TPM's EKpub.
|
||||||
|
|
||||||
- Privacy protection of client identifiers may be needed, in which case
|
- Privacy protection of client identifiers may be needed, in which case
|
||||||
|
@ -288,7 +288,7 @@ protocol:
|
||||||
![Protocol Diagram](Protocol-Two-Messages.png)
|
![Protocol Diagram](Protocol-Two-Messages.png)
|
||||||
|
|
||||||
(In this diagram we show the use of a TPM simulator on the server side
|
(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 server will validate that the `timestamp` is near the current time,
|
||||||
the EKcert (if provided, else the EKpub), the signature using the
|
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)
|
![Protocol Diagram](Protocol-Three-Messages.png)
|
||||||
|
|
||||||
(In this diagram we show the use of a TPM simulator on the server side
|
(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
|
NOTE well that in this protocol, like single round trip attestation
|
||||||
protocols using only decrypt-only EKs, it is *essential* that the AKcert
|
protocols using only decrypt-only EKs, it is *essential* that the AKcert
|
||||||
|
|
|
@ -291,16 +291,18 @@ necessarily yields a new name.
|
||||||
> restricted keys. Still, it may be useful to illustrate cryptographic
|
> restricted keys. Still, it may be useful to illustrate cryptographic
|
||||||
> object naming with one particularly important use of it.
|
> object naming with one particularly important use of it.
|
||||||
|
|
||||||
A pair of functions, `TPM2_MakeCredential()` and
|
A pair of functions,
|
||||||
`TPM2_ActivateCredential()`, illustrate the use of cryptographic object
|
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
|
||||||
naming as a binding or a sort of authorization function.
|
[`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")
|
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) can be
|
||||||
to a target TPM such that the target will _only be willing to decrypt
|
used to encrypt a datum (a "credential") to a target TPM such that the
|
||||||
it_ if *and only if* the application calling `TPM2_ActivateCredential()`
|
target will _only be willing to decrypt it_ if *and only if* the
|
||||||
to decrypt that credential has access to some key named by the sender,
|
application calling `TPM2_ActivateCredential()` to decrypt that
|
||||||
and that name is a cryptographic name that the sender can and must
|
credential has access to some key named by the sender, and that name is
|
||||||
compute for itself.
|
a cryptographic name that the sender can and must compute for itself.
|
||||||
|
|
||||||
The semantics of these two functions can be used to defeat a
|
The semantics of these two functions can be used to defeat a
|
||||||
cut-and-paste attack in attestation protocols.
|
cut-and-paste attack in attestation protocols.
|
||||||
|
@ -312,21 +314,21 @@ keys, each with zero, one, or more children keys:
|
||||||
|
|
||||||
```
|
```
|
||||||
seed
|
seed
|
||||||
|
|
/|\
|
||||||
|
|
/ | \
|
||||||
v
|
v v v
|
||||||
primary key (asymmetric encryption)
|
primary key (asymmetric encryption)
|
||||||
|
|
/|\
|
||||||
|
|
/ | \
|
||||||
v
|
v v v
|
||||||
secondary keys (of any kind)
|
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:
|
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 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
|
A restricted signing key can be used to sign only TPM-generated content
|
||||||
as part of specific TPM restricted signing commands. Such content
|
as part of specific TPM restricted signing commands. Such content
|
||||||
always begins with a magic byte sequence. Conversely, the TPM refuses
|
always begins with a magic byte sequence. Conversely, the TPM refuses
|
||||||
to sign externally generated content that starts with that magic byte
|
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
|
A restricted decryption key can only be used to decrypt ciphertexts
|
||||||
whose plaintexts have a certain structure. In particular these are used
|
whose plaintexts have a certain structure. In particular these are used
|
||||||
for `TPM2_MakeCredential()`/`TPM2_ActivateCredential()` to allow the
|
for [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) /
|
||||||
TPM-using application to get the plaintext if and only if (IFF) the
|
[`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
|
||||||
plaintext cryptographically names an object that the application has
|
to allow the TPM-using application to get the plaintext if and only if
|
||||||
access to. This is used to communicate secrets ("credentials") to TPMs.
|
(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
|
Another operation that a restricted decryption key can perform is
|
||||||
PKIX certificates.
|
[`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
|
## Attestation
|
||||||
|
|
||||||
|
|
21
TPM-Commands/TPM2_Certify.md
Normal file
21
TPM-Commands/TPM2_Certify.md
Normal 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
25
TPM-Commands/TPM2_Duplicate.md
Normal 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
22
TPM-Commands/TPM2_Import.md
Normal 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
19
TPM-Commands/TPM2_Load.md
Normal 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)
|
||||||
|
|
Loading…
Reference in a new issue