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

Add Enrollment tutorial; describe more TPM commands

Browse source
This commit is contained in:
Nicolas Williams 2021-05-25 16:13:14 -05:00
parent 3b4191c0ae
commit 57cc17c6cb
6 changed files with 628 additions and 53 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

393
Attestation/README.md
View file

@ -64,6 +64,26 @@ Attestation is done by a client computer with a TPM interacting with an
attestation service over a network. This requires a network protocol attestation service over a network. This requires a network protocol
for attestation. for attestation.
## Intended Audience
Readers should have read the [TPM introduction tutorial](/Intro/README.md).
## Enrollment
[Enrollment](/Enrollment/README.md) is the process and protocol for
onboarding devices into a network / organization. For example, adding
an IoT to a home network, a server to a data center, a smartphone or
tablet or laptop to a persons set of personal devices, etc.
Generally attestation protocols apply to enrolled devices. Enrollment
protocols _may_ be very similar to attestation protocols, or even
actually be sub-protocols of attestation protocols. Enrollment
protocols can also be separate from attestation altogether.
This tutorial mostly covers only attestation of/by enrolled devices.
For more about enrollment see the tutorial specifically for
[enrollment](/Enrollment/README.md).
## Notation ## Notation
- `Encrypt_<name>` == encryption with the named private or secret key - `Encrypt_<name>` == encryption with the named private or secret key
@ -78,6 +98,70 @@ for attestation.
- `{"key":<value>,...}` == JSON text - `{"key":<value>,...}` == JSON text
- `TPM2_MakeCredential(<args>)` == outputs of calling `TPM2_MakeCredential()` with `args` arguments - `TPM2_MakeCredential(<args>)` == outputs of calling `TPM2_MakeCredential()` with `args` arguments
- `TPM2_Certify(<args>)` == outputs of calling `TPM2_Certify()` with `args` arguments - `TPM2_Certify(<args>)` == outputs of calling `TPM2_Certify()` with `args` arguments
- `XK` == `<X>` key, for some `<X>` purpose (the TPM-resident object and its private key)
- `EK` == endorsement key (the TPM-resident object and its private key)
- `AK` == attestation key (the TPM-resident object and its private key)
- `TK` == transport key (the TPM-resident object and its private key)
- `XKpub` == `<X>`'s public key, for some `<X>` purpose
- `EKpub` == endorsement public key
- `AKpub` == attestation public key
- `TKpub` == transport public key
- `XKname` == `<X>`'s cryptographic name, for some `<X>` purpose
- `EKname` == endorsement key's cryptographic name
- `AKname` == attestation key's cryptographic name
## Threat Models
Some threats that an attestation protocol and implementation may want to
address:
- attestation client impersonation
- attestation server impersonation
- unauthorized firmware and/or OS updates
- theft or compromise of of attestation servers
- theft of client devices or their local storage (e.g., disks, JBODs)
- theft of client devices by adversaries capable of decapping and
reading the client's TPM's NVRAM
The attestation protocols we discuss will provide at least partial
protection against impersonation of attestation clients: once a TPM's
EKpub/EKcert are bound to the device in the attestation server's
database, that TPM can only be used for that device and no others.
All the attestation protocols we discuss will provide protection against
unauthorized firmware and/or OS updates via attestation of root of trust
measurements (RTM).
The attestation protocols we discuss will provide protection against
impersonation of attestation servers without necessarily authenticating
the servers to the clients in traditional ways (e.g., using TLS server
certificates). The role of the attestation server will be to deliver to
clients secrets and credentials they need that can only be correct and
legitimate if the server is authentic. As well, an attestation server
may unlock network access for a client, something only an authentic
server could do.
We will show how an attestation server can avoid storing any cleartext
secrets.
Theft of _running_ client devices cannot be fully protected against by
an attestation protocol. The client must detect being taken from its
normal environment and shutdown in such a way that no secrets are left
in cleartext on any of its devices. Frequent attestations might be used
to detect theft of a client, but other keepalive signalling options are
possible.
Theft of non-running client devices can be protected against by having
the client shutdown in such a way that no secrets are left in cleartext
on any of its devices. Such client devices may be configured to need
the help of an attestation server to recover the secrets it needs for
normal operation.
Full protection against decapping of TPM chips is not possible, but
protection against off-line use of secrets stolen from TPM chips is
possible by requiring that the client be on-line and attest in order to
obtain secrets that it needs to operate. This allows for revocation of
stolen clients, which would result in attestation protocol failures.
## Proof of Possession of TPM ## Proof of Possession of TPM
@ -314,7 +398,7 @@ is persisted both, in the client TPM and in the attestation service's
database: database:
``` ```
<having previously successfully enrolled AKpub and bound it to EKpub...> <having previously successfully enrolled>
CS0: timestamp, AKpub, PCRs, eventlog, CS0: timestamp, AKpub, PCRs, eventlog,
TPM2_Quote(AK, PCRs, extra_data)=Signed_AK({hash-of-PCRs, misc, extra_data}) TPM2_Quote(AK, PCRs, extra_data)=Signed_AK({hash-of-PCRs, misc, extra_data})
@ -505,10 +589,6 @@ PCRs are desired, then this becomes a one round trip protocol.
An AKcert will be added to the Safeboot protocol soon. An AKcert will be added to the Safeboot protocol soon.
### Actual Protocols: ...
(TBD)
## Attestation Protocol Patterns and Actual Protocols (signing-only EKs) ## Attestation Protocol Patterns and Actual Protocols (signing-only EKs)
Some TPMs come provisioned with signing-only endorsement keys in Some TPMs come provisioned with signing-only endorsement keys in
@ -609,8 +689,8 @@ A schema for the attestation server's database entries might look like:
"previous_PCRs": "<...>", "previous_PCRs": "<...>",
"proposed_PCRs": "<...>", "proposed_PCRs": "<...>",
"ak_cert_template": "<AKCertTemplate>", "ak_cert_template": "<AKCertTemplate>",
"secrets": "<secrets>", "resetCount": "<resetCount value from last quote>",
"resetCount": "<resetCount value from last quote>" "secrets": "<see below>"
} }
``` ```
@ -660,12 +740,28 @@ then an administrator would confirm that the client just did a
firmware/OS upgrade and if so replace the `previous_PCRs` with the firmware/OS upgrade and if so replace the `previous_PCRs` with the
`proposed_PCRs`, then the client could attempt attestation again. `proposed_PCRs`, then the client could attempt attestation again.
## Dealing with Secrets # Delivery of Secrets to Attestation Clients
An attestation server might want to return storage/filesystem decryption An attestation server might have to return storage/filesystem decryption
key-encryption-keys to a client. But one might not want to store those key-encryption-keys (KEKs) to a client. But one might not want to store
keys in the clear on the attestation server. As well, one might want a those keys in the clear on the attestation server. As well, one might
break-glass way to recover those secrets. want a break-glass way to recover those secrets.
Possible goals:
- store secrets that clients need on the attestation server
- do not store plaintext or plaintext-equivalent secrets on the
attestation server
- allow for adding more secrets to send to the client after enrollment
- provide a break-glass recovery mechanism
Note that in all cases the client does get direct access to various
secrets. Using a TPM to prevent direct software access to those secrets
would not be performant if, for example, those secrets are being used to
encrypt filesystems. We must inherently trust the client to keep those
secrets safe when running.
## Break-Glass Recovery
For break-glass recovery, the simplest thing to do is to store For break-glass recovery, the simplest thing to do is to store
`Encrypt_backupKey({EKpub, hostname, secrets})`, where `backupKey` is an `Encrypt_backupKey({EKpub, hostname, secrets})`, where `backupKey` is an
@ -675,53 +771,252 @@ the ciphertext to the offline system where the private backup key is
kept, decrypt it, and then use the secrets manually to recover the kept, decrypt it, and then use the secrets manually to recover the
affected system. affected system.
Here are some ideas for how to make an attestation client depend on the ## Secret Transport Sub-Protocols
attestation server giving it keys needed to continue booting after
successful attestation:
- Store `TPM2_MakeCredential(EKpub, someObjectName, key0), Encrypt_key0(secrets)`. Here we describe several possible sub-protocols of attestation protocols
for secret transport. This list is almost certainly not exhaustive.
In this mode the server sends the client the stored data, then client ### Store a `TPM2_MakeCredential()` Payload
gets to recreate `someObject` (possibly by loading a saved object or
by re-creating it on the same non-NULL hierarchy from the same
primary seed using the same template and extra entropy) on its TPM so
that the corresponding call to `TPM2_ActivateCredential()` can
succeed, then the client recovers `key0` and decrypts the encrypted
secrets. Here `someObject` can be trivial and need only exist to
make the `{Make,Activate}Credential` machinery work.
TPM replacement and/or migration of a host from one physical system [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md) and
to another can be implemented by learning the new system's TPM's [`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
EKpub and using the offline `backupKey` to compute can use any kind of loaded object with a private area as the "credential
`TPM2_MakeCredential(EKpub_new, someObjectName, key0)` and update the object name" and "credential object handle" arguments of the two calls,
host's entry. respectively. During attestation we need to use an AK for this object
due to the need to have a signature key for
[`TPM2_Quote()`](/TPM-Commands/TPM2_Quote.md), and we want that AK to
have `stClear` set, meaning that it is ephemeral, rendering the outputs
of `TPM2_MakeCredential(EKpub, AKname, secrets)` ephemeral as well,
therefore `TPM2_MakeCredential(EKpub, AKname, secrets)` must be called
on each attestation, which means the `secrets` also have to be ephemeral
or else must be stored in cleartext on the attestation server.
- Alternatively generate a non-restricted decryption private key using However, we can use a key that does not have `stClear` set as the
a set template and extra entropy, on the same non-NULL hierarchy credential object. A long-term key that survives reboots.
(i.e., from the same seed), enroll the public key to this private key
in an attestation protocol, and have the attestation server store
secrets encrypted to that public key.
(The EK cannot be used this way because it is restricted.) > We'd like to use the EK itself, however,
> [that is not actually possible](https://github.com/tpm2-software/tpm2-tools/issues/1883)
> because the `activateHandle` argument to
> [`TPM2_ActivateCredential()`](/TPM-Commands/TPM2_ActivateCredential.md)
> requires `ADMIN` role, and on most TPMs the auth policy for the EK
> does not provide any way to satisfy it for this usage. Though in
> principle this should be possible, and it would be very convenient if
> it was.
- Store a secret value that will be extended into an application PCR So for this approach one has to create a long-term attestation key that
that is used as a policy PCR for unsealing a persistent object stored we shall call the `LTAK`, and then the server can store
on the client's TPM. `TPM2_MakeCredential(EKpub, LTAKname, secrets)` without knowing the
secrets.
In this mode the server sends the client the secret PCR extension The client has to use
value, and the client uses it to extend a PCR such that it can then [`TPM2_CreatePrimary()`](/TPM-Commands/TPM2_CreatePrimary.md) or
unseal the real storage / filesystem decryption keys. [`TPM2_CreateLoaded()`](/TPM-Commands/TPM2_CreateLoaded.md) in order to
deterministically create the same `LTAK` (again, without the `stClear`
attribute), else if it uses
[`TPM2_Create()`](/TPM-Commands/TPM2_Create.md) then it must store the
key save file somewhere (possibly in the attestation server!) or make
the key object persistent.
Using a PCR and a policy on the key object allows for a clever ```
break-glass secret recovery mechanism by using a compound extended <having previously successfully enrolled
authorization (EA) policy that allows either unsealing based on a and saved
PCR, or maybe based on an password-based HMAC (with machine passwords long_term_Credential =
stored in a safe). TPM2_MakeCredential(EKpub, LTAKname, secrets_key) ||
Encrypt_secrets_key(long_term_secrets)>
- A hybrid of the previous options, where the server stores a secret CS0: timestamp, AKpub, PCRs, eventlog,
PCR extension value wrapped with `TPM2_MakeCredential()`. TPM2_Quote(AK, PCRs, extra_data)=Signed_AK({hash-of-PCRs, misc, extra_data})
SC0: {TPM2_MakeCredential(EKpub, AKname, session_key),
Encrypt_session_key(long_term_Credential)}
```
Other ideas? New secrets can be added at any time without interaction with the
client if the attestation server recalls the `LTAKname`.
The schema for storing secrets transported this way would be:
```JSON
{
"EKpub": "<EKpub>",
"hostname": "<hostname>",
"EKcert": "<EKcert in PEM, if available>",
"previous_firmware_profile": "FWProfile0",
"current_firmware_profiles": ["FWProfile1", "FWProfile2", "..."],
"previous_operating_system_profiles": "OSProfile0",
"current_operating_system_profiles": ["OSProfile1", "OSProfile2", "..."],
"previous_PCRs": "<...>",
"proposed_PCRs": "<...>",
"ak_cert_template": "<AKCertTemplate>",
"resetCount": "<resetCount value from last quote>",
"secret store and transport fields":"vvvvvvvvvvvvvvvvvv",
"LTAKname": "<...>",
"secrets": ["<MakeCredential_0>", "<MakeCredential_1>", "..", "<MakeCredential_N>"]
"secrets_backup": ["<RSA_Encrypt_to_backup_key(...)", "..."],
}
```
### Use an Unrestricted Decryption Transport Key (TK) for Secret Transport (client-side)
Another option is to generate an asymmetric key-pair at device
enrollment time (we shall call this the "transport key", or `TK`), and
store:
- the `TKpub`, and
- zero, one, or more secrets encrypted in the `EKpub`.
The client has to use
[`TPM2_CreatePrimary()`](/TPM-Commands/TPM2_CreatePrimary.md) or
[`TPM2_CreateLoaded()`](/TPM-Commands/TPM2_CreateLoaded.md) in order to
deterministically create the same `TK` (without the `stClear`)
attribute, else if it uses
[`TPM2_Create()`](/TPM-Commands/TPM2_Create.md) then it must store the
key save file somewhere (possibly in the attestation server!) or make
the key object persistent.
New secrets can be added at any time without interaction with the
client.
```JSON
{
"EKpub": "<EKpub>",
"hostname": "<hostname>",
"EKcert": "<EKcert in PEM, if available>",
"previous_firmware_profile": "FWProfile0",
"current_firmware_profiles": ["FWProfile1", "FWProfile2", "..."],
"previous_operating_system_profiles": "OSProfile0",
"current_operating_system_profiles": ["OSProfile1", "OSProfile2", "..."],
"previous_PCRs": "<...>",
"proposed_PCRs": "<...>",
"ak_cert_template": "<AKCertTemplate>",
"resetCount": "<resetCount value from last quote>",
"secret store and transport fields":"vvvvvvvvvvvvvvvvvv",
"TKpub": "<TKpub in PEM>",
"secrets": ["<RSA_Encrypt_0>", "<RSA_Encrypt_1>", "..", "<RSA_Encrypt_N>"]
"secrets_backup": ["<RSA_Encrypt_to_backup_key(...)", "..."],
}
```
### Use an Unrestricted Decryption Transport Key (TK) for Secret Transport (server-side)
Another option is to generate an asymmetric key-pair at device
enrollment time (we shall call this the "transport key", or `TK`), and
store:
- the TK exported to the client device's TPM (i.e., the output of
`TPM2_Duplicate()` called on that private key to export it to the
client's TPM's EKpub), and
- the ciphertext resulting from encrypting long-term secrets to that
TK.
At attestation time the server can send back these two values to the
client, and then the client can `TPM2_Import()` and then `TPM2_Load()`
the duplicated (exported) TK, then use it to `TPM2_RSA_Decrypt()` the
encrypted long-term secrets.
New secrets can be added at any time without interaction with the
client.
```JSON
{
"EKpub": "<EKpub>",
"hostname": "<hostname>",
"EKcert": "<EKcert in PEM, if available>",
"previous_firmware_profile": "FWProfile0",
"current_firmware_profiles": ["FWProfile1", "FWProfile2", "..."],
"previous_operating_system_profiles": "OSProfile0",
"current_operating_system_profiles": ["OSProfile1", "OSProfile2", "..."],
"previous_PCRs": "<...>",
"proposed_PCRs": "<...>",
"ak_cert_template": "<AKCertTemplate>",
"resetCount": "<resetCount value from last quote>",
"secret store and transport fields":"vvvvvvvvvvvvvvvvvv",
"TKdup": "<output of TPM2_Duplicate(EKpub, TK)>",
"TKpub": "<TKpub in PEM>",
"secrets": ["<RSA_Encrypt_0>", "<RSA_Encrypt_1>", "..", "<RSA_Encrypt_N>"]
"secrets_backup": ["<RSA_Encrypt_to_backup_key(...)", "..."],
}
```
### Store a Secret PCR Extension Value for Unsealing Data Objects
The attestation server could store in plaintext a secret that it will
returned encrypted to the client's EKpub vias `TPM2_MakeCredential()`,
and which the client must use to extend a PCR (e.g., the debug PCR) to
get that PCR into the state needed to unseal a persistent data object on
the TPM.
Because the sealed data object may itself be stored in cleartext in the
TPM's NVRAM, and because an attacker might be able to decap a stolen
client device's TPM and recover the TPM's NVRAM contents and seeds, the
client might store an encrypted value in that sealed data object that
the TPM does not have the keey to decrypt. The decryption key would be
sent by the attestation server (possibly being the same secret as is
extended into that PCR).
```JSON
{
"EKpub": "<EKpub>",
"hostname": "<hostname>",
"EKcert": "<EKcert in PEM, if available>",
"previous_firmware_profile": "FWProfile0",
"current_firmware_profiles": ["FWProfile1", "FWProfile2", "..."],
"previous_operating_system_profiles": "OSProfile0",
"current_operating_system_profiles": ["OSProfile1", "OSProfile2", "..."],
"previous_PCRs": "<...>",
"proposed_PCRs": "<...>",
"ak_cert_template": "<AKCertTemplate>",
"resetCount": "<resetCount value from last quote>",
"secret store and transport fields":"vvvvvvvvvvvvvvvvvv",
"unseal_key": "<key>",
"secrets_backup": ["<RSA_Encrypt_to_backup_key(...)", "..."],
}
```
### Store Secrets in Plaintext, Encrypt to EKpub Using `TPM2_MakeCredential()`
As the title says, one option is to store the secrets in plaintext and
send them encrypted to the EKpub via
[`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md).
Because [`TPM2_MakeCredential()`](/TPM-Commands/TPM2_MakeCredential.md)
encrypts only a small secret, it goes without saying that that secret
would be a one-time use symmetric encryption key that would be used to
encrypt the actual secrets.
This is, naturally, the least desirable option.
```JSON
{
"EKpub": "<EKpub>",
"hostname": "<hostname>",
"EKcert": "<EKcert in PEM, if available>",
"previous_firmware_profile": "FWProfile0",
"current_firmware_profiles": ["FWProfile1", "FWProfile2", "..."],
"previous_operating_system_profiles": "OSProfile0",
"current_operating_system_profiles": ["OSProfile1", "OSProfile2", "..."],
"previous_PCRs": "<...>",
"proposed_PCRs": "<...>",
"ak_cert_template": "<AKCertTemplate>",
"resetCount": "<resetCount value from last quote>",
"secret store and transport fields":"vvvvvvvvvvvvvvvvvv",
"secrets": ["<secret_0>", "<secret_1>", "<secret_N>"]
}
```
# Security Considerations
TBD
# References # References

139
Enrollment/README.md Normal file
View file

@ -0,0 +1,139 @@
# Device Enrollment
Device Enrollment is the act of registering a device -anything from an
IoT to a server- and creating the state that will be referenced in
future [attestations](/Attestation/README.md) from that device.
This can be as simple as sending the device's endorsement key
certificate (EKcert) to a registration server (possibly authenticating
to that server using some administrator user's credentials), to a more
complex protocol similar to [attestation](/Attestation/README.md).
## Online Enrollment
Online enrollment means that the device to be enrolled interacts with an
enrollment service over a network.
## Off-line Enrollment
Off-line enrollment means that the device to be enrolled *does not*
interact with an enrollment service.
For example, one might scan an endorsement key (EK) public key or
certificate from a QR code on a shipment manifest and then enroll the
device using only that information.
# Server-Side State to Create during Enrollment
- device name <-> EKpub binding
- enrolling user/admin
- that the device has a valid TPM (i.e., the EKcert validates to a
trusted TPM vendor's trust anchor)
- initial root of trust measurement (RTM)
- backup, secret recovery keys
- encrypted secrets to send to the device
# Client-side State to Create during Enrollment
- encrypted filesystems?
- device credentials? (e.g., TLS server certificates, Kerberos keys ["keytabs"], etc.)
# Secrets Transport
Every time an enrolled device reboots, or possibly more often, it may
have to connect to an attestation server to obtain secrets from it that
the device needs in order to proceed. For example, filesystem
decryption keys, general network access, device authentication
credentials, etc.
See [attestation](/Attestation/README.md) for details of how to
transport secrets onto an enrolled device post-enrollment.
# Enrollment Semantics
- online vs. off-line
- client device trust semantics:
- bind device name and EKpub on first use ("BOFU")?
- enroll into inventory and then allow authorized users to bind a
device name to an EKpub on a first-come-first-served basis?
- enrollment server trust semantics:
- trust on first use (TOFU) (i.e., trust the first enrollment server
found)
- pre-install a trust anchor on the client device
- use a user/admin credential on the device to establish trust on
the server (e.g., intrinsically to how user authentication works,
or having the user review and approve the server's credentials)
# Threat Models
Threats:
- enrollment server impersonation
- enrollment of rogue devices
- eavesdroppers
- DoS
A typical enrollment protocol for servers in datacenters may well not
bother protecting against all of the above.
A typical enrollment protocol for IoTs in a home network also may well
not bother protecting against any of the above.
Enrollment protocols for personal devices must protect against all the
listed threats except DoS attacks.
# Enrollment Protocols
## Trivial Enrollment Protocols
The simplest enrollment protocols just have the client device send its
EKcert to the enrollment server. The enrollment server may have a user
associate enrolled devices with device IDs (e.g., hostnames), and the
device's enrollment is complete.
## Enrollment Protocols with Proof of Possession and Attestation
A more complex enrollment protocol would have the device attest to
possession of the EK whose EKpub is certified by its EKcert, and might
as well also perform attestation of other things, such as RTM.
An enrollment protocol with proof of possession might look a lot like
the [two round trip attestation
protocol](/Attestation/README.md#two-round-trip-stateless-attestation-protocol-patterns),
with the addition of `enrollment_data` in the last message from the
client to the server (server authentication not shown):
```
CS0: [ID], EKpub, [EKcert], AKpub, PCRs, eventlog, timestamp,
TPM2_Quote(AK, PCRs, extra_data)=Signed_AK({hash-of-PCRs, misc, extra_data})
SC0: {TPM2_MakeCredential(EKpub, AKpub, session_key), ticket}
CS1: {ticket, MAC_session_key(CS0), CS0, Encrypt_session_key(enrollment_data)}
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
(new)
SC1: Encrypt_session_key({AKcert, filesystem_keys, etc.})
<extra_data includes timestamp>
```
where
```
enrollment_data = { Encrypt_TK(secrets), [TKpub], [HK_pub] }
secrets = any secrets generated on the client side
TKpub = public part of transport key for encrypting secrets to the
client
HKpub = public part of a host key for host authentication
```
## Enrollment Protocols for Personal Devices
Enrollment of personal devices in their owners' personal device groups
can be a lot like Bluetooth device pairing. Where such devices have
TPMs then perhaps there is a role for the TPM to play in enrollment.
# Security Considerations
TBD

16
Intro/README.md
View file

@ -348,10 +348,18 @@ 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 ("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 platform's, and even the platform's user(s)' identities.
The `TPM2_CreatePrimary()` and `TPM2_CreateLoaded()` commands create key The [`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) command creates
objects deterministically from the hierarchy's seed and the "template" primary key objects deterministically from the hierarchy's seed and the
used to create the key (which includes a "unique" area that provides "template" used to create the key (which includes a "unique" area that
"entropy" to the key derivation function). provides "entropy" to the key derivation function).
The [`TPM2_Create()`](TPM2_Create.md) command creates a ordinary
objects.
The [`TPM2_CreateLoaded()`](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).
## Key Wrapping and Resource Management ## Key Wrapping and Resource Management

49
TPM-Commands/TPM2_Create.md Normal file
View file

@ -0,0 +1,49 @@
# `TPM2_Create()`
This command creates an ordinary key object.
The created object can then be loaded with [`TPM2_Load()`](TPM2_Load.md).
To decide whether to use [`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md),
`TPM2_Create()`, or [`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md)
refer to table 28 in section 2.7 of the [TCG TPM Library part 1:
Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf).
If you need to `TPM2_CertifyCreation()` that a TPM created some object,
you must use [`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
`TPM2_Create()`.
If you need to seal the object to a PCR selection, you must use
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
`TPM2_Create()`.
If you need to create a derived object, you must use
[`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md).
If you need to create an ordinary object, use `TPM2_Create()` or
[`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md).
If you need to create a primary object, use
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
[`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md).
## Inputs
- `TPMI_DH_OBJECT parentHandle`
- `TPM2B_PUBLIC inPublic`
- `TPM2B_DATA outsideInfo`
- `TPML_PCR_SELECTION creationPCR`
## Outputs (success case)
- `TPM_HANDLE objectHandle`
- `TPM2B_PRIVATE outPrivate`
- `TPM2B_PUBLIC outPublic`
- `TPM2B_CREATION_DATA creationData`
- `TPM2B_DIGEST creationHash`
- `TPMT_TK_CREATION creationTicket`
## References
- [TCG TPM Library part 3: Commands, section 12.1](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)

43
TPM-Commands/TPM2_CreateLoaded.md Normal file
View file

@ -0,0 +1,43 @@
# `TPM2_CreateLoaded()`
This command creates a key object and loads it. The object can be a
primary key, in which case `TPM2_CreateLoaded()` behaves just like
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md). Or the object can be
`ordinary` or `derived`.
The created object can then be loaded with [`TPM2_Load()`](TPM2_Load.md).
To decide whether to use `TPM2_CreateLoaded()`,
[`TPM2_Create()`](TPM2_Create.md), or
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) refer to table 28 in
section 2.7 of the [TCG TPM Library part 1:
Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf).
If you need to `TPM2_CertifyCreation()` that a TPM created some object,
you must use [`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
[`TPM2_Create()`](TPM2_Create.md).
If you need to seal the object to a PCR selection, you must use
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
[`TPM2_Create()`](TPM2_Create.md).
If you need to create a derived object, you must use
`TPM2_CreateLoaded()`.
## Inputs
- `TPMI_DH_PARENT+ parentHandle`
- `TPM2B_SENSITIVE_CREATE inSensitive`
- `TPM2B_TEMPLATE inPublic`
## Outputs (success case)
- `TPM_HANDLE objectHandle`
- `TPM2B_PRIVATE outPrivate` (optional)
- `TPM2B_PUBLIC outPublic`
- `TPM2B_NAME name`
## References
- [TCG TPM Library part 3: Commands, section 12.9](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)

41
TPM-Commands/TPM2_CreatePrimary.md Normal file
View file

@ -0,0 +1,41 @@
# `TPM2_CreatePrimary()`
This command creates a primary key object.
The created object can then be loaded with [`TPM2_Load()`](TPM2_Load.md).
To decide whether to use [`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md),
[`TPM2_Create()`](TPM2_Create.md), or
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) refer to table 28 in
section 2.7 of the [TCG TPM Library part 1:
Architecture](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part1_Architecture_pub.pdf).
If you need to `TPM2_CertifyCreation()` that a TPM created some object,
you must use [`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
[`TPM2_Create()`](TPM2_Create.md).
If you need to seal the object to a PCR selection, you must use
[`TPM2_CreatePrimary()`](TPM2_CreatePrimary.md) or
[`TPM2_Create()`](TPM2_Create.md).
If you need to create a derived object, you must use
[`TPM2_CreateLoaded()`](TPM2_CreateLoaded.md).
## Inputs
- `TPMI_RH_HIERARCHY+ primaryHandle`
- `TPM2B_TEMPLATE inPublic`
- `TPM2B_DATA outsideInfo`
- `TPML_PCR_SELECTION creationPCR`
## Outputs (success case)
- `TPM_HANDLE objectHandle`
- `TPM2B_CREATION_DATA creationData`
- `TPM2B_DIGEST creationHash`
- `TPMT_TK_CREATION creationTicket`
- `TPM2B_NAME name`
## References
- [TCG TPM Library part 3: Commands, section 24.1](https://trustedcomputinggroup.org/wp-content/uploads/TCG_TPM2_r1p59_Part3_Commands_pub.pdf)