Unseal Hosts Hardware TPM Endorsement Keys
Unseal a secret that is bound to an endorsement key. Provided with duplicate key data, load the key as a child of the specified endorsement key using the TPM2_Import command and then unseal the secret data using the TPM2_Unseal command.
The duplicate key must include only outer wrapping; inner wrapping is not supported. The duplicate key cannot have a complex authorization policy (e.g. including command selection, locality, etc). Only PCR policy authorization is supported at this time.
Trusted Platform Module Library Part 1: Architecture, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 23.3 Duplication
Trusted Platform Module Library Part 3: Commands, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 13.3 TPM2_Import
Trusted Platform Module Library Part 3: Commands, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 12.7 TPM2_Unseal
if you do not have all of the privileges described as follows: - The resource HostSystem referenced by the parameter host requires Host.Tpm.Unseal.
Request
URLURL
https://{api_host}/api/vcenter/trusted-infrastructure/hosts/{host}/hardware/tpm/{tpm}/endorsement-keys/{key}?action=unseal
Path Parameters
Path Parameters
string
host
Required
Identifier of the host. The parameter must be an identifier for the resource type: HostSystem.
string
tpm
Required
the TPM identifier. The parameter must be an identifier for the resource type: com.vmware.vcenter.trusted_infrastructure.hosts.hardware.Tpm.
string
key
Required
the endorsement key identifier. The parameter must be an identifier for the resource type: com.vmware.vcenter.trusted_infrastructure.hosts.hardware.tpm.EndorsementKey.
Header Parameters
Header Parameters
string
vmware-api-session-id
Required
Required session ID, acquired from Create Session API under CIS product
vmware-api-session-id example
"b00db39f948d13ea1e59b4d6fce56389"
Request Body
Request Body
TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec of mimetype application/json
Required
the unseal spec.
{
"private_area": "string",
"public_area": "string",
"seed": "string"
}
string
private_area
Required
A private area that contains a secret to be unsealed. The private area is symmetrically encrypted with the seed value derived from EndorsementKeys.UnsealSpec.seed.
The private area is a TPM2B_PRIVATE structure.
Trusted Platform Module Library Part 2: Structures, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 12.3.7 TPM2B_PRIVATE
This private area is used as the “duplicate” input to the TPM2_Import command.
Trusted Platform Module Library Part 3: Commands, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 13.3 TPM2_Import
string
public_area
Required
The public area which corresponding to the EndorsementKeys.UnsealSpec.private-area secret that is being unsealed. The public area is a TPM2B_PUBLIC structure.
Trusted Platform Module Library Part 2: Structures, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 12.2.5 TPM2B_PUBLIC
This public area is used as the “objectPublic” input to the TPM2_Import command.
Trusted Platform Module Library Part 3: Commands, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 13.3 TPM2_Import
string
seed
Required
A seed value that is encrypted by the TPM endorsement key. The seed will be decrypted with the endorsement key and then will be used as a symmetric key to decrypt EndorsementKeys.UnsealSpec.private-area. This ensures that only a TPM with the expected endorsement key can unseal the secret.
The seed value is a TPM2B_ENCRYPTED_SECRET structure.
Trusted Platform Module Library Part 2: Structures, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 11.4.3 TPM2B_ENCRYPTED_SECRET
This seed is used as the “inSymSeed” input to the TPM2_Import command.
Trusted Platform Module Library Part 3: Commands, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 13.3 TPM2_Import
policy_pcr
Optional
PCR policy required to unseal the secret. Used as input to the TPM2_PolicyPCR command on a session that is created for issuing the TPM2_Unseal command.
Trusted Platform Module Library Part 3: Commands, Family “2.0”, Level 00 Revision 01.59, November 8, 2019, Section 23.7 TPM2_PolicyPCR
If unset, then a zeroed authorization policy is used for the TPM2_Unseal session.
Authentication
This operation uses the following authentication methods.
Response
Response
Response BodyResponse Body
200 OK returns
string
formatted as binary
of type application/json
The unsealed secret.
Errors
default
‘Default’ means this response is used for all HTTP codes that are not covered individually for this operation.
Code Samples
PowerCLI Client SDK Example
$TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec = Initialize-TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec -PublicArea -PrivateArea -Seed
Invoke-UnsealHostTpmKey -Host "MyHost" -Tpm "MyTpm" -Key "MyKey" -TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec $TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec
PowerCLI Client SDK All Parameters Example
$TrustedInfrastructureHostsHardwareTpmEndorsementKeysPolicyPcrSpec = Initialize-TrustedInfrastructureHostsHardwareTpmEndorsementKeysPolicyPcrSpec -Pcrs -PcrDigest
$TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec = Initialize-TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec -PublicArea -PrivateArea -Seed -PolicyPcr $TrustedInfrastructureHostsHardwareTpmEndorsementKeysPolicyPcrSpec
Invoke-UnsealHostTpmKey -Host "MyHost" -Tpm "MyTpm" -Key "MyKey" -TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec $TrustedInfrastructureHostsHardwareTpmEndorsementKeysUnsealSpec
cURL Command
curl -X POST -H "vmware-api-session-id: b00db39f948d13ea1e59b4d6fce56389" -H "Content-Type: application/json" -d '{"policy_pcr":{"pcr_digest":"string","pcrs":"string"},"private_area":"string","public_area":"string","seed":"string"}' https://{api_host}/api/vcenter/trusted-infrastructure/hosts/{host}/hardware/tpm/{tpm}/endorsement-keys/{key}?action=unseal
Vendor Extensions
This operation contains the following vendor extensions defined in the spec:
x-vmw-doc-operation: unseal
Availability
Added in 8.0.0.1
