Makes the TPM 2.0 accessible via the standard OpenSSL API and command-line tools, so one can add TPM support to (almost) any OpenSSL 3.0 based application.
The tpm2-openssl project
-
Implements a provider that integrates the Trusted Platform Module (TPM 2.0) operations to the OpenSSL 3.0, which is the next version of OpenSSL after 1.1.1.
-
Follows the new OpenSSL provider API and strictly avoids any legacy API. Therefore this implementation:
- Is compatible with OpenSSL 3.0 and (hopefully) future OpenSSL versions.
- Does not work with any previous version, including the current OpenSSL 1.1.
-
Is based on a major refactoring of the tpm2-tss-engine. The code is still there, but largely reshuffled to match the new OpenSSL API. Therefore this implementation:
- Retains (almost) all functions of the tpm2-tss-engine, although the command-line interface and the API has changed.
- Does not modify format of the
TSS2 PRIVATE KEYfile, so keys created by the previous version still work. - Respects the original license and copyright.
-
Relies on the Enhanced System API (ESAPI) from the Trusted Computing Groups (TCG) TPM Software Stack (TSS 2.0) and uses the tpm2-tss software stack implementation, version 3.2.0 or later.
Instructions for building and installing the tpm2 provider are provided in the INSTALL.md file.
Instructions for how releases are conducted, please see the RELEASE.md file.
The tpm2 provider functions can be used via the
openssl
command-line tool,
or via the
libcrypto API.
No TPM-specific API calls are needed: the applications may be completely unaware that the keys being used are stored within TPM. However, the application has to:
- Load the tpm2 provider, in some cases along with the default provider.
- (When both providers are loaded) use the
?provider=tpm2property query when fetching the crypto algorithms.
Connect to the TPM2 using the
openssl -provider
option,
or using the
OSSL_PROVIDER
API functions.
The TPM2OPENSSL_TCTI environment variable may be used to specify the
TPM Command Transmission Interface (TCTI).
The OSSL_PROVIDER_self_test API may be used to invoke the TPM self-test operation.
Provides encryption (TPM2_EncryptDecrypt) using the
openssl enc
or the
EVP_Cipher API.
The AES-128, AES-192, AES-256, CAMELLIA-128, CAMELLIA-192 and CAMELLIA-256
algorithm in the ECB, CBC, OFB, CFB or CTR mode is supported.
Provides digest calculation (TPM2_Hash) using the
openssl dgst
or the
EVP_Digest API.
The SHA-1, SHA-256, SHA-384 and SHA-512 algorithm is supported.
Provides a random number generation (TPM2_GetRandom) using the
openssl rand
or the
EVP_RAND API.
Provides key generation (TPM2_Create) using the
openssl genpkey
or the
EVP_PKEY API
for the
RSA and
RSA-PSS keys, as well as the
EC keys
with a NIST curve P-192, P-224, P-256, P-384 or P-521.
The private key gets stored as a PEM (TSS2 PRIVATE KEY) or DER file.
For example, to generate a RSA key using TPM:
openssl genpkey -provider tpm2 -algorithm RSA -out testkey.priv
Provides
OSSL_STORE
and
OSSL_DECODER API
to load (TPM2_Load) a private key from a previously generated file, as well as
persistent keys generated with the
tpm2-tools. Both the hexadecimal
key handle as well as the serialized object file may be used. These URI
prefixes may be used with any openssl command.
The corresponding public key can be stored using the
openssl pkey
or the
OSSL_ENCODER API.
The SubjectPublicKeyInfo (PUBLIC KEY) and PKCS1 (RSA PUBLIC KEY) form,
either PEM or DER is supported.
For example, to load a persistent key and export its public portion:
openssl pkey -provider tpm2 -in handle:0x81000000 -pubout -out testkey.pub
Provides asymmetric signature (TPM2_Sign) using the
openssl pkeyutl -sign
or the
EVP_DigestSign API.
The PKCS1 (rsassa) and PSS (rsapss) padding (signing scheme) is supported.
For example, to sign arbitrary data:
openssl pkeyutl -provider tpm2 -inkey handle:0x81000000 -sign -rawin -in testdata -out testdata.sig
Signing using a restricted signing key is possible, e.g. one can sign arbitrary
data using the TPM attestation key (AK) created by tpm2_createak.
Such keys are compatible with e.g. the strongSwan
TPM Plugin.
Therefore, OpenSSL could be used to create and deploy VPN keys/certificates.
Provides RSA decryption (TPM2_RSA_Decrypt) using the
openssl pkeyutl -decrypt
or the
EVP_PKEY_decrypt API.
Provides ECDH shared secret derivation (TPM2_ECDH_ZGen) using the
openssl pkeyutl -derive
or the
EVP_PKEY_derive API.
Provides all operations required for certificate signing using
openssl req,
Certificate Authority (CA) operation using
openssl ca
and the Certificate Management Protocol (CMP) client using
openssl cmp.
Provides all operations required for TLS authentication based on a TPM2-based key.
Please mind the limited number of transient key and sequence objects that can
be concurrently loaded in the TPM. The number of ongoing digest operations and
the number of loaded private keys is limited. The in-kernel resource manager
(/dev/tpmrm) is also memory constrained.
If your application needs to create a large number of objects, we recommend using
the user-space resource manager
with a sufficiently large --max-transients argument.
The TPM is a cryptographic processor with a secure key storage. It is not an accelerator. Many operations are slower than a pure software implementation.
For user convenience the tpm2 provider implements also Symmetric Operations that do not use the secure storage, but we recommend using the OpenSSL's default provider instead in performance critical applications.
Not every OpenSSL operation will work with the TPM: some are not specified by the TCG TPM specification, some might not be implemented by your TPM chip.
The list of algorithms supported by the tpm2 provider on your actual TPM can be retrieved using the openssl list commands.
Algorithms that do not require the TPM hardware, such as public key operations, hashes or symmetric ciphers, can be fetched from the OpenSSL's default provider.
When you get stuck, remember: Read-Search-Ask.
- Read the error message and the documentation
- Search Google
- Ask for help
You can ask a question via an GitHub Issue, or send an email to the TPM2 mailing list.
tpm2-openssl is distributed under the BSD 3 Clause License.