blob: 724303f0eb70cf273cb57f1ece11ea531fb6bb92 [file] [log] [blame]
README for the OpenSSL TPM 2.0 engine
Author: James Bottomley <James.Bottomley@HansenPartnership.com>
Mailing List: openssl-tpm2-engine@groups.io
ABOUT
This package contains 2 sets of code, a command-line utility used to
generate a TSS key blob and write it to disk and an OpenSSL engine which
interfaces with the TSS API. Because this application uses the TPM
cryptographically, it must be build with the IBM TSS:
http://ibmswtpm.sourceforge.net/ibmtss2.html
Prebuilt binaries for a lot of distributions on the Open SUSE Build Service
https://build.opensuse.org/package/show/home:jejb1:TPM/ibmtss
You can also find this package and a range of other TPM tools built at
https://build.opensuse.org/package/show/home:jejb1:TPM
BUILDING
Requirements: OpenSSL, IBM TSS
$ configure [--enable-debug] [--with-openssl=/path/to/custom/openssl]
$ make
# make install
RUNNING
create_tpm2_key: create a TPM key and write it to disk
usage: create_tpm2_key [options] <filename>
Options:
-a|--auth require a password for the key [NO]
-h|--help print this help message
-s|--key-size key size in bits [2048]
-n|--name-scheme name algorithm to use sha1 [sha256] sha384 sha512
-p|--parent-handle persistent handle of parent key
-w|--wrap [file] wrap an existing openssl PEM key
-c|--key-policy [file] TPM key policy
For full options see the command help.
Key auth: Default=none. If -a is specified, you will be prompted on the
command line using OpenSSL for a passphrase.
Key enhanced auth (NEW): Default=none. If -c is specified, the new key
will be associated with the policy provided.
OpenSSL TPM engine
Included in this package is a sample openssl.cnf file, which can be used
to turn on use of the TPM engine in apps where OpenSSL config support is
compiled in.
Policy File Format
The policy file should contain a rule for each line, where rules
can be generated for example with the policymakerpcr tool from IBM TSS.
Example (PolicyPCR):
$ tsspolicymakerpcr -bm 10000 -if policypcr16aaasha256.txt -v -pr -of policies/policypcr.txt >> policy.txt
where policypcr16aaasha256.txt contains the desired value of PCR 16.
Example (PolicyAuthValue):
$ echo 0000016b >> policy.txt
USES
Create a self-signed cert using the TPM engine:
0. Good practice is to generate the RSA version of the primary storage
seed and place it at well known location 81000001 (Microsoft Spec).
To do this, you need to manipulate the non resource manager
interface so the keys aren't lost when the process dies:
# TPM_DEVICE=/dev/tpm0 tsscreateprimary -hi o -st -rsa
Handle 80000000
# TPM_DEVICE=/dev/tpm0 tssevictcontrol -hi o -ho 80000000 -hp 81000001
# TPM_DEVICE=/dev/tpm0 tssflushcontext -ha 80000000
where 80000000 is the the handle and is always returned by the
first command. You must do the final tssflushcontext otherwise the
transient key won't get flushed since you used the non resource
manager interface.
Note: tsscreateprimary will take a while to run (50s on my laptop)
while the TPM derivces an RSA key from the primary seed. This long
time is why you want to store a permanent copy of the derived key.
1. Generate an external key and wrap it for the TPM:
$ openssl genrsa 2048 > <private key>
$ create_tpm2_key -w <private key> [-p 81000001] <key file>
Note: specifying the parent is optional (and you need to have
created it in step 0) but if you leave it out, the key will still
end up parented to the primary storage seed and the TPM will have
to re-derive the RSA version of that seed each time you use it
(possibly taking 50s or more each time)
Note: because the RSA private key is sent to the TPM encrypted, the
tss has to have access to the public part of the parent key (if you
didn't specify a parent, this public part will be created when the
parent key is derived from the storage primary seed), so you may
need to do tssreadpublic -p 81000001 before it will work.
2. Make the openssl certificate request:
$ openssl req -keyform engine -engine tpm2 -key <key file> -new -x509 -days 365 -out <certfilename>
3. Test using openssl:
$ openssl s_server -cert <certfilename> -www -accept 4433 -keyform engine -engine tpm2 -key <keyfilename>
$ konqueror https://localhost:4433