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