mirror of
https://github.com/tpm2dev/tpm.dev.tutorials.git
synced 2024-12-22 01:42:09 +00:00
Expand on restricted keys; describe more TPM commands
This commit is contained in:
Nicolas Williams
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
|
||||
_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:
|
|||
|
||||
|
||||
(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.
|
|||
|
||||
|
||||
(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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
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