NAME¶

openssl_tpm2_engine - engine or provider of TPM2 keys for OpenSSL

SYNOPSIS¶

Describes how to use the OpenSSL TPM2 engine or provider (engines work for all current OpenSSL versions but have a special engine key file API; providers only work for OpenSSL 3 but use normal key file APIs).

DESCRIPTION¶

Acts as a plugin to OpenSSL to support TPM2 keys. If the plugin is an engine, the correct engine specifications (ENGINE_load_private_key(3ssl)) must be used for key files. If the plugin is a provider then OpenSSL will automatically recognize TPM2 key files in place of ordinary OpenSSL PEM or DER key files (PEM_read_PrivateKey(3ssl), d2i_PrivateKey_bio(3ssl), d2i_PrivateKey_fp(3ssl)).

The engine or provider is named "tpm2" and can either be specified on the command line or can be automatically loaded in openssl.cnf in either the engines or providers section, see OpenSSL config(5ssl).

OPTIONS¶

Config file options for the engine (see Openssl config(5ssl) for details) are

NVPREFIX Set the Non Volatile key prefix (default //nvkey:)

PIN Set the Storage Root Hierarchy or key authority

THREAT MODEL AND MITIGATION¶

The standard threat of an interposer sniffing host to TPM communications is thwarted by using session encryption and HMAC. However the mechanism by which a secret session salt is communicated to the TPM by encrypting it to a primary key is vulnerable to interception, as is the assumption, for policy bound keys, that the TPM will never be able to rewind PCR state.

The attack which can rewind PCR state is termed a reset attack (see the Linux Kernel TPM security documentation for details). An attack on session salting usually happens because the user of the TPM usually uses a primary key to encrypt the session salt but cannot check the public key it encrypts to for authenticity, so an active interposer can fake a primary key create function to return its own public key and thus decrypt the encrypted salt (which it may then re-encrypt and pass on to the underlying TPM, thus evading detection).

Both of these attacks may be thwarted by certifying the null name at start of day and salting the sessions with a secret encrypted to the certified null key. The reason for using the null primary to salt sessions is that if the TPM is ever reset (see the Linux Kernel TPM security documentation for details) the null seed will change and the null name check will notice and error out. Additionally if an active interposer is ever present which tries to trick session salting by lying about the public key this will be detected because the null name will again mismatch.

The Linux kernel (from version 6.10 on) will export the name of the null key it used for session salting and will detect a reset attack on its own, allowing us to certify an unbroken chain from the kernel's first use of the TPM to our use. For kernel versions less than 6.10, the null seed may be certified on boot and stored in /etc/null.name for later by the session salting.

ENVIRONMENT¶

When compiled for the Intel TSS the following IBM TSS environment variables are understood:

TPM_INTERFACE_TYPE either device or socsim. socsim will activate the
tcti interface for either the ms or swtpm (see
SWTPM)

SWTPM either mssim or swtpm. Identifies the flavour of
vTPM being used for tcti.

The library code now uses an initial constructor to pull in the null name (meaning the name of the EC P-256 storage primary derived from the null seed) from a file at start of day so it can be checked every time a null primary is generated. This style of primary generation and checking is used for salted sessions. The code will look firstly for the kernel provided null name in /sys/class/tpm0/tpm/null_name and then fall back to /etc/null.name. The following environment variables influence this:

TPM_NULL_NAME the name of the file containing the null name. If
this is present, the match is required.

TPM_NULL_REQUIRE if set (to anything) requires the null name check
to pass

Note that the null name is only imported from the file for checking against, it isn't certified on the fly, so the design use case is that something else will certify the null name using attest_tpm2_primary(1) as part of the init system ensuring it is safe for all subsequent consumers to rely on.

FILES¶

/etc/ssl/openssl.cnf

/sys/class/tpm0/tpm/null_name

/etc/null.name

If the last file is used, it must be created fresh on every boot (because the null seed will change on every boot). This can be accomplished using the attest_tpm2_primary(1) command from a boot script.

AUTHOR¶

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

REPORTING BUGS¶

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