News, tips, partners, and perspectives for the Oracle Solaris operating system

TPM Key Migration in Solaris

TPM Key Migration in Solaris


alt="Infineon TPM 1.2 chip" width="180" height="135" border="0" />

Solaris platforms use

the TPM 1.2 chip

"TPM" stands for "Trusted Platform Module," a hardware device that provides many security
functions, including storage of encryption keys.
For more information, see Wylly's blog on
Solaris 11 TPM Support.

In Solaris 11.1, Wyllys Ingersoll added the ability to migrate keys
from one TPM to another TPM.
TPM migration is is especially useful when upgrading hardware, migrating a
system to a new platform, or after reinitializing the TPM.
The following describes this new feature.

Since the introduction of TPM Support in Solaris 11, Solaris has had
the ability to generate keys that are bound to a specific TPM and which
cannot be used anywhere else. This tight binding to a specific device
is a security feature of the TPM and TPM keys. Whenever a user or application
creates a persistent TPM key, internally it is put into a key hierarchy
that is organized in a tree-like fashion with a Storage Root Key (SRK)
at the top of the tree and all other user and system keys that get
created are either a child of the SRK or a child to a key somewhere
below the SRK. SRK keys can never be migrated or moved from one TPM to
another. This can cause a problem if the platform (motherboard, TPM, etc)
ever has to be replaced because if the underlying TPM is changed, as this
would cause all keys that were tied to the old TPM to become unusable and
any data encrypted with those keys would not be recoverable. It is also
a problem in situations where the disk containing the TPM persistent keys
is moved to a new platform with a different TPM.

TPM Key Scheme before the TPM Migration feature:
Without a Migratable Root Key

The Trusted Computing Group (TCG)
specifications allow for keys to be created with a "migratable"
attribute which allows them to be migrated from one parent key to another.
By enforcing a new key hierarchy, we can ensure that keys can be migrated
and recovered in the event that the underlying device has changed.
This features generates a sub-SRK (called a Migratable Root Key or MRK) that
all applications that wish to preserve the ability to migrate keys can use as
the parent key. This new Migratable Root Key can then be migrated if necessary and
automatically enables all of the descendent keys to be migrated. Only the
root of the tree needs to be migrated and all children in the hierarchy
automatically continue to work as usual since they are only bound to
their parent.

New TPM Key Scheme with the TPM Migration feature:
With a Migratable Root Key

TPM Migration Details

Persistent (stored) TPM keys are identified by UUID values.

  • The SRK has a
    specific well-known SRK UUID defined as 00000000-0000-0000-0000-00000000001
  • The new MRK introduces a new well-known MRK UUID, 00000000-0000-0000-0000-0000000000b

UUIDs are always stored in network byte order, aka Big Endian (see RFC 4122).

When the platform owner issues the "tpmadm init" command to take ownership of the
TPM and establish an owner passphrase, tpmadm also creates the new Migratable
Root Key in the system key database. Additionally, it will establish the
migration key and migration data that will be used in the event of a future
migration request. The software migration data and migration key is stored in
/var/tpm/system/tpm-migration.dat and

The migration key data will be protected with the same passphrase entered as
the TPM owner passphrase. However, if the administrator later changes the
TPM owner passphrase with the "tpmadm auth" command, the migration key
passphrase will not be changed.

Directory /var/tpm/system/ is read-only for root:sys and requires
elevated privileges to access and perform a migration. See "Privileges" section below.

Any system application that creates persistent TPM keys
(libkmf(3LIB) through PKCS#11 provider pkcs11_tpm(5) or tpmadm(1M))
uses the "MRK" key as the parent.

The tpmadm(1M) application administers TPM migration.
The tpmadm migrate sub-command
useful for anyone who wants to export their persistent keys and move them
to another TPM.
The tpmadm sub-commands are explained here and in the tpmadm(1M) man page.

The "tpmadm keyinfo" command lists your keys:

$ tpmadm keyinfo
[SYSTEM] 00000000-0000-0000-0000-000000000001 (loaded)
[SYSTEM] 00000000-0000-0000-0000-00000000000b
[USER] bc25ec53-239e-6ae8-f888-9e46d8f8f40f
[USER] f5cc255c-2bd5-cb2d-e961-874f82dad286

To create the initial migration blob and key for the persistent key "UUID", use:

# tpmadm migrate export UUID [MigDataFile MigKeyfile]

For example to export the MRK, use:

# tpmadm migrate export 00000000-0000-0000-0000-00000000000b

The "tpmadm migrate export" command:

  • Prompts for key password (if necessary) and migration password. If the
    key does not require authorization, the user will only be prompted for
    the migration key password (which is required).
  • This operation generates two files: a "migration blob" (wrapped key) and
    a "migration key" to be used in future migrations. The output files
    created are "tpm-migration.dat" and "tpm-migration.key" unless they
    are specified on the command line.
  • The data files created will be created with 0400 permissions (read-only for user).
  • This operation requires the user to enter the TPM owner
    authorization password as well as any other authorization passwords
    for any parent keys in the chain.

To Import a key into the users persistent key database, use:

# tpmadm migrate import [MigDataFile MigKeyFile [ParentUUID] [NewKeyUUID]]

The "tpmadm migrate import" command:

  • The key will be made a child of the given ParentUUID. If ParentUUID is not given, the
    imported key will be a child of the system MRK UUID.
  • If NewKeyUUID is not given, a the system will assign a new UUID and report
    it to the user upon completion of the command.
  • The user will be prompted for the migration password used in the "export" step.
  • When the "tpmadm migrate import" command is given with no other arguments,
    it will perform the migration of the SYSTEM MRK using the data files
    created when "tpmadm init" command was orignally performed.
    If the MRK data and key files are not found, the command fails.
  • This operation requires the user to enter the TPM owner
    authorization password as well as any other authorization passwords
    for any parent keys in the chain.

Upgrading TPM Keys From Solaris 11

Any TPM keys that a user may have already created that were not created with
the "migratable" flag, can never be moved to a new parent key. Unfortunately,
the existing key hierarchy created and used by pkcs11_tpm does not create
migratable keys and so any existing pkcs11 TPM tokens will never be able to
be migrated. However, the impact of an upgrade to the new key scheme introduced by
this project should be minimal for these reasons:

  • Existing keys that are marked as non-migratable and are already parented
    under the SRK, will continue to work as long as the underlying TPM
    never changes and the disk on which the keys reside doesn't move to a
    new platform with a different TPM.

  • The PKCS#11 TPM provider was updated to use the new MRK as the parent for
    the storage keys used by the PKCS#11 provider and all keys
    created will be marked as migratable where appropriate. This will ensure
    that the key hierarchy associated with an individual PKCS#11 TPM token
    will be migratable in the future.

Tpmadm Privileges

The tpmadm(1M) "tpmadm init", and "tpmadm migrate" subcommands
require elevated privileges because they need to access root-owned files. The existing
"TPM Administration" rights profile supports this ability without
requiring tpmadm to be setuid or requiring the user to have full root privilege.
Users with the TPM Administration profile may use the
"tpmadm init" and "tpmadm migrate" sub-commands without becoming root.

The following is the security profile entry in file

TPM Administration:RO::Administer Privileged TPM Operations:auths=solaris.smf.manage.tcsd,solaris.smf.value.tcsd

And file

solaris.smf.value.tcsd:::Change TPM Administation value properties::

solaris.smf.manage.tcsd:::Manage TPM Administration service states::


  • SRK (Storage Root Key) resides on the TPM chip
  • MRK (Migratable Root Key) resides off the TPM on the local filesystem key store
  • MRK allows keys to migrate to another system
  • MRK allows backup as keys
  • SRK wraps MRK, which wraps a tree hierarchy of all other keys
  • This schema allows an infinite number of keys off the TPM that are protected by the TPM


Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.