NAME¶

seal_tpm2_data - seal a blob of data for a TPM

SYNOPSIS¶

seal_tpm2_data [options] <filename>

DESCRIPTION¶

Used to create a sealed blob of data which can be unsealed via the TPM. Possible uses for this blob of data include as a symmetric key, which is the use in the linux kernel trusted key infrastructure.

OPTIONS¶

-a, --auth

The data blob requires authorization

-b, --auth-parent <pwd>

Specify the parent key password (default EmptyAuth)

-d, --da

mark the key as having Dictionary Attack implications. This means that if the key password is incorrectly presented too many times, the TPM may Implement DA mitigation and refuse connections for a while

-h, --help

print this help message

-p, --parent-handle <handle>

parent for the key, can either be a persistent key or a hierarchy. the hierarchies can be 'platform', 'owner', 'null' or 'endorsement'. The seeds used for derivation are platform, storage, null or endorsement respectively

-v, --version

print package version

-k, --password <pwd>

use this password instead of prompting

-m, --nomigrate

Create a sealed data bundle that can be migrated to other systems.

-n, --name-scheme <scheme>

name algorithm to use sha1 [sha256] sha384 sha512

-x, --pcr-lock <pcrs>

Lock the created key to the specified PCRs By current value. See PCR VALUES for details about formatting

--locality <loc>

Can only be unsealed in a set of localities described by the <loc> bitmap

--signed-policy <key>

Add a signed policy directive that allows policies signed by the specified public <key> to authorize unsealing

--secret <handle>

Tie authorization of the key to the Authorization of a different object Identified by <handle>.

-i, --import <pubkey>

Create an importable key with the outer wrapper encrypted to <pubkey>

-c, --policy

Specify a policy for unsealing the data

PCR VALUES¶

The PCR values are specified as

<bank>:<list>

Where <bank> is any supported PCR hash bank and list specifies the PCRs to lock the key to as both comma separated individual values as well as comma separated ranges. So

sha256:1,3 means PCRs 1 and 3 in the sha256 bank

sha512:1,3-5 means PCRs 1,3,4 and 5 in the sha512 bank

IMPORT¶

In some cases, there may be a need to wrap a key without access to the TPM it will be use on. For these cases an importable key may be specified with the --import option. For this to work, you must use a public key corresponding exactly to the one the importing TPM will use (Note: only Elliptic Curve parents are currently supported). For instance the owner seed elliptic curve storage key may be produced as

tsscreateprimary -hi o -st -ecc nistp256 -opem parent.pub

Then a sealed data file may be wrapped to the TPM via:

echo "data" | seal_tpm2_data --import parent.pub seal.tpm

Note that certain parameters must be assumed about a parent when it is wrapped, like the template (must be standard restricted decryption key) and the name hash (must be sha256).

SECRETS IN OTHER OBJECTS¶

When the option --secrets <handle> is used, it creates a sealed blob whose authorization password is conditioned on the password of a different object identified by <handle>. Usually this is a permanent NV index, but could be any object. The design of this policy is to allow the password to be changed without updating the sealed blob (simply by changing the authorization of the other object). Because most unseal applications can only request a single password, blobs with a --secret policy may not additionally have an --auth option to also require passing in the password embedded in the blob.

SIGNED POLICIES¶

When the option --signed-policy <key> is used, it creates a sealed blob whose policy can be extended by anyone possessing the private part of <key>. The <key> presented must be a public key (so the owner of the private key doesn't have to be the owner of the created tpm sealed blob).

Note that sealed blobs created with --signed-policy cannot be used until at least one signed policy is added.

EXAMPLES¶

Create a sealed data blob to the storage parent (owner hierarchy)

echo somedatatoseal | seal_tpm2_key -p owner seal.tpm

Unseal the data

unseal_tpm2_key seal.tpm

AUTHOR¶

Written by James Bottomley <James.Bottomley@HansenPartnership.com>

REPORTING BUGS¶

Report bugs to <openssl-tpm2-engine@groups.io>

COPYRIGHT¶

Copyright 2017 by James Bottomley License LGPL-2.1-only