| =head1 NAME |
| |
| swtpm-create-tpmca - Tool to create a local CA for swtpm_localca |
| |
| =head1 SYNOPSIS |
| |
| B<swtpm-create-tpmca [OPTIONS]> |
| |
| =head1 DESCRIPTION |
| |
| B<swtpm-create-tpmca> is a tool to create a TPM 1.2 based CA that |
| can be used by B<swtpm_localca> to sign EK and platform certificates. |
| The CA uses a GnuTLS key to sign certificates. To do this, |
| GnuTLS talks to the TPM 1.2 using the B<tcsd> (TrouSerS) daemon. |
| |
| Since the TPM CA's certificate must be signed by a CA, a root certificate authority |
| will also be created and will sign this certificate. The root CA's |
| private key and certificate will be located in the same directory as the |
| signing key and have the names swtpm-localca-rootca-privkey.pem and |
| swtpm-localca-rootca-cert.pem respectively. The environment variable |
| SWTPM_ROOTCA_PASSWORD can be set for the password of the root CA's |
| private key. |
| |
| Note: This tool is experimental. See the section on known issues below. |
| |
| The following options are supported: |
| |
| =over 4 |
| |
| =item B<--dir dir> |
| |
| The directory where the keys will be written to. An existing root CA with |
| the files I<swtpm-localca-rootca-privkey.pem> and |
| I<swtpm-localca-rootca-cert.pem> in this directory will be reused. If |
| either one of these files does not exist, a new root CA will be created. |
| |
| =item B<--overwrite> |
| |
| Overwrite the contents of the output directory. |
| |
| =item B<--register> |
| |
| Register the key with TCSD. For the key to be available for signing, |
| the same user that created the TPM CA has to run the swtpm_localca tool |
| later on. If this option is not passed, the private key is written |
| into a file and can be used by others as well. |
| |
| =item B<--key-password s> |
| |
| The new signing key will get this password. |
| |
| Note: Due to a bug in GnuTLS certtool it may be necessary to use the |
| same password for the signing key as for the SRK. |
| |
| =item B<--srk-password s> |
| |
| The TPM SRK password. |
| |
| Note: Since GnuTLS tpmtool does not support the 'well known' password |
| of 20 zero bytes, the SRK password must be set. |
| |
| =item B<--outfile filename> |
| |
| The name of a file where to write the swtpm-localca.conf configuration |
| to. |
| |
| =item B<--owner owner> |
| |
| The name or uid number of the owner who will own the directory and |
| outfile file. This option only has an effect if this swtpm-create-tpmca |
| is run by the root user. |
| |
| =item B<--group group> |
| |
| The name or gid number of the group who will own the directory and |
| outfile file. This option only has an effect if this swtpm-create-tpmca |
| is run by the root user. |
| |
| =item B<--tss-tcsd-hostname> |
| |
| The hostname where tcsd is running on. The default hostname is 'localhost'. |
| |
| =item B<-tss-tcsd-port> |
| |
| The TCP port on which tcsd is listening for messages. The default port is |
| 30003. |
| |
| =item B<--tpm2> |
| |
| The TPM to use for signing the certificates is a TPM 2 and Intel's TSS stack |
| must be running (tpm2-abrmd) along with its PKCS11 module. |
| The TPM 2 PKCS11 module must have been initialized using the tpm2_ptool. |
| |
| The environment variables SWTPM_PKCS11_PIN and SWTPM_PKCS11_SO_PIN should be |
| set to hold the PINs. If SWTPM_PKCS11_PIN is not set then the default PIN |
| 'swtpm-tpmca' will be used. SWTPM_PKCS11_SO_PIN is needed for creating the |
| token and must be explicitly set as an environment variable. |
| |
| =item B<--pid pimary-object-id> |
| |
| The primary object id that the tpm2_ptool returns upon 'init'. |
| |
| =item B<-help, -h, -?> |
| |
| Display the help screen and exit. |
| |
| =back |
| |
| =head1 EXAMPLE |
| |
| The following example creates an intermediate TPM CA and writes the keys |
| into /var/lib/swtpm-localca and the swtpm_localca configuration to |
| /etc/swtpm-localca.conf. It can then be used for signing certificates of |
| newly created B<swtpm> TPMs. |
| |
| If the host's TPM is a TPM 1.2, we need to start the tcsd first and can |
| then create the TPM key and TPM CA certificate: |
| |
| #> sudo systemctl start tcsd |
| #> sudo /usr/share/swtpm/swtpm-create-tpmca \ |
| --dir /var/lib/swtpm-localca \ |
| --overwrite \ |
| --outfile /etc/swtpm-localca.conf \ |
| --srk-password password \ |
| --key-password password \ |
| --group tss |
| statedir = /var/lib/swtpm-localca |
| signingkey = tpmkey:file=/var/lib/swtpm-localca/swtpm-localca-tpmca-privkey.pem |
| issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem |
| certserial = /var/lib/swtpm-localca/certserial |
| TSS_TCSD_HOSTNAME = localhost |
| TSS_TCSD_PORT = 30003 |
| signingkey_password = password |
| parentkey_password = password |
| |
| |
| Alternatively, if the host's TPM is a TPM 2 and Intel's TPM 2 stack is |
| installed, we need to start tpm2-abrmd first and can then create the TPM key |
| and TPM CA certificate: |
| |
| #> sudo systemctl start tpm2-abrmd |
| #> tpm2_ptool init |
| action: Created |
| id: 1 # this is the --pid parameter below |
| #> sudo SWTPM_PKCS11_PIN="mypin 123" SWTPM_PKCS11_SO_PIN=123 /usr/share/swtpm/swtpm-create-tpmca \ |
| --dir /var/lib/swtpm-localca \ |
| --overwrite \ |
| --outfile /etc/swtpm-localca.conf \ |
| --group tss \ |
| --tpm2 \ |
| --pid 1 |
| statedir = /var/lib/swtpm-localca |
| signingkey = pkcs11:model=SW%20%20%20TPM\;manufacturer=IBM\;serial=0000000000000000\;token=swtpm-tpmca-1\;id=%31\;object=swtpm-tpmca-key\;type=private |
| issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem |
| certserial = /var/lib/swtpm-localca/certserial |
| SWTPM_PKCS11_PIN = mypin 123 |
| |
| Note: This also works for non-root users by adapting the --dir and --outfile |
| parameters here and below by changing the --dir parameter and adding a --config |
| parameter. |
| |
| To test either one of the above TPM CAs, run the following command: |
| |
| #> swtpm_localca \ |
| --type ek --ek x=11,y=13 \ |
| --dir /tmp --vmid test --tpm2 \ |
| --tpm-spec-family 2.0 --tpm-spec-revision 146 --tpm-spec-level 00 \ |
| --tpm-model swtpm --tpm-version 20170101 --tpm-manufacturer IBM |
| |
| The --tpm2 in this command indicates that the TPM for which the certificate |
| is created is a TPM 2. |
| |
| =head1 KNOWN ISSUES |
| |
| The interaction of GnuTLS certtool with the TPM TCSD daemon may cause so |
| many TPM (key) authentication failures that the TPM refuses to accept any |
| more authenticated commands until the TPM's owner sends it the |
| TPM_ORD_ResetLockValue command. The reason for this is that certtool first |
| tries to use 20 zero bytes for the SRK password and only then prompts for |
| and uses the required SRK password. The GnuTLS tpmtool does not support 20 |
| zero bytes for the SRK password, so forces the usage of a 'real' password. |
| |
| The effect of the authentication failures may be that the TPM CA cannot sign |
| certificates since the TPM does not accept authenticated commands. |
| |
| =head1 SEE ALSO |
| |
| B<swtpm_localca>, B<swtpm-localca.conf>, B<tcsd> |
| |
| =head1 REPORTING BUGS |
| |
| Report bugs to Stefan Berger <stefanb@linux.ibm.com> |