# Trusted Platform Module (TPM) support

OpenConnect supports the use of private keys secured or "wrapped" by a TPM. Instead of being stored inside the trusted hardware as with typical PKCS#11 keys, the key is encrypted by the TPM and handed back to the user to be saved in a PEM file. Only the same TPM can decrypt the file, and use the private key.

Use of TPM-wrapped keys is intended to be entirely transparent. OpenConnect will automatically use the TPM when presented with an appropriate PEM file with a TPM-wrapped key.

When OpenConnect is built with OpenSSL, the appropriate TPM ENGINE must be installed correctly on the system, and OpenConnect will load and use it automatically when appropriate.

For GnuTLS builds of OpenConnect, it needs to have been built with the appropriate TPM (v1 or v2) support built-in.

## TPM v1

TPM v1 wrapped keys appear in the form of a PEM file marked with the tag:

    -----BEGIN TSS KEY BLOB-----

These files can be created by the `create_tpm_key` tool which is part of the OpenSSL TPM ENGINE or the tpmtool which is part of the GnuTLS distribution.

## TPM v2

As from the 8.0 release, OpenConnect supports TPM v2 wrapped keys. These have the PEM tag:

    -----BEGIN TSS2 PRIVATE KEY-----

There are two ENGINE implementations for TPM v2 with OpenSSL, based on different TSS libraries.

`openssl_tpm2_engine` is based on IBM's TPM 2.0 TSS, while `tpm2-tss-engine` uses the Intel/TCG stack. OpenConnect can use either ENGINE.

The GnuTLS build of OpenConnect can use either TSS library, with TPMv2 support implemented natively in OpenConnect. GnuTLS does not have its own TPMv2 support yet (GnuTLS issue #594).

### Creating / importing keys

Each of the above-referenced OpenSSL ENGINE implementations comes with a tool to create keys in the appropriate format.

The `create_tpm2_key` tool from the IBM version can be used to 'wrap' existing keys, using its `-w` option. To take an existing key file and encrypt it for use by the TPM, for example:

- `create_tpm_key -w key_file.pem tpm_key.pem`

Presumably you would then delete the original key file, since having the private key protected by the TPM is a bit pointless if you just leave it lying around on disk anyway.

The Intel version does not support importing existing keys; this is tpm2-tss-engine issue #39.

### Legacy TPMv2 key format

Older keys from `openssl_tpm2_engine` may have the tag:

    -----BEGIN TSS2 KEY BLOB-----

This format is also supported by the GnuTLS builds of OpenConnect.