man/man8/swtpm-create-tpmca.pod

   1 =head1 NAME
   2
   3 swtpm-create-tpmca - Tool to create a local CA for swtpm_localca
   4
   5 =head1 SYNOPSIS
   6
   7 B<swtpm-create-tpmca [OPTIONS]>
   8
   9 =head1 DESCRIPTION
  10
  11 B<swtpm-create-tpmca> is a tool to create a TPM 1.2 based CA that
  12 can be used by B<swtpm_localca> to sign EK and platform certificates.
  13 The CA uses a GnuTLS key to sign certificates. To do this,
  14 GnuTLS talks to the TPM 1.2 using the B<tcsd> (TrouSerS) daemon.
  15
  16 Since the TPM CA's certificate must be signed by a CA, a root certificate authority
  17 will also be created and will sign this certificate. The root CA's
  18 private key and certificate will be located in the same directory as the
  19 signing key and have the names swtpm-localca-rootca-privkey.pem and
  20 swtpm-localca-rootca-cert.pem respectively. The environment variable
  21 SWTPM_ROOTCA_PASSWORD can be set for the password of the root CA's
  22 private key.
  23
  24 Note: This tool is experimental. See the section on known issues below.
  25
  26 The following options are supported:
  27
  28 =over 4
  29
  30 =item B<--dir dir>
  31
  32 The directory where the keys will be written to. An existing root CA with
  33 the files I<swtpm-localca-rootca-privkey.pem> and
  34 I<swtpm-localca-rootca-cert.pem> in this directory will be reused. If
  35 either one of these files does not exist, a new root CA will be created.
  36
  37 =item B<--overwrite>
  38
  39 Overwrite the contents of the output directory.
  40
  41 =item B<--register>
  42
  43 Register the key with TCSD. For the key to be available for signing,
  44 the same user that created the TPM CA has to run the swtpm_localca tool
  45 later on. If this option is not passed, the private key is written
  46 into a file and can be used by others as well.
  47
  48 =item B<--key-password s>
  49
  50 The new signing key will get this password.
  51
  52 Note: Due to a bug in GnuTLS certtool it may be necessary to use the
  53 same password for the signing key as for the SRK.
  54
  55 =item B<--srk-password s>
  56
  57 The TPM SRK password.
  58
  59 Note: Since GnuTLS tpmtool does not support the 'well known' password
  60 of 20 zero bytes, the SRK password must be set.
  61
  62 =item B<--outfile filename>
  63
  64 The name of a file where to write the swtpm-localca.conf configuration
  65 to.
  66
  67 =item B<--owner owner>
  68
  69 The name or uid number of the owner who will own the directory and
  70 outfile file. This option only has an effect if this swtpm-create-tpmca
  71 is run by the root user.
  72
  73 =item B<--group group>
  74
  75 The name or gid number of the group who will own the directory and
  76 outfile file. This option only has an effect if this swtpm-create-tpmca
  77 is run by the root user.
  78
  79 =item B<--tss-tcsd-hostname>
  80
  81 The hostname where tcsd is running on. The default hostname is 'localhost'.
  82
  83 =item B<-tss-tcsd-port>
  84
  85 The TCP port on which tcsd is listening for messages. The default port is
  86 30003.
  87
  88 =item B<--tpm2>
  89
  90 The TPM to use for signing the certificates is a TPM 2 and Intel's TSS stack
  91 must be running (tpm2-abrmd) along with its PKCS11 module.
  92 The TPM 2 PKCS11 module must have been initialized using the tpm2_ptool.
  93
  94 The environment variables SWTPM_PKCS11_PIN and SWTPM_PKCS11_SO_PIN should be
  95 set to hold the PINs. If SWTPM_PKCS11_PIN is not set then the default PIN
  96 'swtpm-tpmca' will be used. SWTPM_PKCS11_SO_PIN is needed for creating the
  97 token and must be explicitly set as an environment variable.
  98
  99 =item B<--pid pimary-object-id>
 100
 101 The primary object id that the tpm2_ptool returns upon 'init'.
 102
 103 =item B<-help, -h, -?>
 104
 105 Display the help screen and exit.
 106
 107 =back
 108
 109 =head1 EXAMPLE
 110
 111 The following example creates an intermediate TPM CA and writes the keys
 112 into /var/lib/swtpm-localca and the swtpm_localca configuration to
 113 /etc/swtpm-localca.conf. It can then be used for signing certificates of
 114 newly created B<swtpm> TPMs.
 115
 116 If the host's TPM is a TPM 1.2, we need to start the tcsd first and can
 117 then create the TPM key and TPM CA certificate:
 118
 119  #> sudo systemctl start tcsd
 120  #> sudo /usr/share/swtpm/swtpm-create-tpmca \
 121                 --dir /var/lib/swtpm-localca \
 122                 --overwrite \
 123                 --outfile /etc/swtpm-localca.conf \
 124                 --srk-password password \
 125                 --key-password password \
 126                 --group tss
 127  statedir = /var/lib/swtpm-localca
 128  signingkey = tpmkey:file=/var/lib/swtpm-localca/swtpm-localca-tpmca-privkey.pem
 129  issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
 130  certserial = /var/lib/swtpm-localca/certserial
 131  TSS_TCSD_HOSTNAME = localhost
 132  TSS_TCSD_PORT = 30003
 133  signingkey_password = password
 134  parentkey_password = password
 135
 136
 137 Alternatively, if the host's TPM is a TPM 2 and Intel's TPM 2 stack is
 138 installed, we need to start tpm2-abrmd first and can then create the TPM key
 139 and TPM CA certificate:
 140
 141  #> sudo systemctl start tpm2-abrmd
 142  #> tpm2_ptool init
 143  action: Created
 144  id: 1                   # this is the --pid parameter below
 145  #> sudo SWTPM_PKCS11_PIN="mypin 123" SWTPM_PKCS11_SO_PIN=123 /usr/share/swtpm/swtpm-create-tpmca \
 146                 --dir /var/lib/swtpm-localca \
 147                 --overwrite \
 148                 --outfile /etc/swtpm-localca.conf \
 149                 --group tss \
 150                 --tpm2 \
 151                 --pid 1
 152  statedir = /var/lib/swtpm-localca
 153  signingkey = pkcs11:model=SW%20%20%20TPM\;manufacturer=IBM\;serial=0000000000000000\;token=swtpm-tpmca-1\;id=%31\;object=swtpm-tpmca-key\;type=private
 154  issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
 155  certserial = /var/lib/swtpm-localca/certserial
 156  SWTPM_PKCS11_PIN = mypin 123
 157
 158 Note: This also works for non-root users by adapting the --dir and --outfile
 159 parameters here and below by changing the --dir parameter and adding a --config
 160 parameter.
 161
 162 To test either one of the above TPM CAs, run the following command:
 163
 164  #> swtpm_localca \
 165         --type ek --ek x=11,y=13 \
 166         --dir /tmp --vmid test --tpm2 \
 167         --tpm-spec-family 2.0 --tpm-spec-revision 146 --tpm-spec-level 00 \
 168         --tpm-model swtpm --tpm-version 20170101 --tpm-manufacturer IBM
 169
 170 The --tpm2 in this command indicates that the TPM for which the certificate
 171 is created is a TPM 2.
 172
 173 =head1 KNOWN ISSUES
 174
 175 The interaction of GnuTLS certtool with the TPM TCSD daemon may cause so
 176 many TPM (key) authentication failures that the TPM refuses to accept any
 177 more authenticated commands until the TPM's owner sends it the
 178 TPM_ORD_ResetLockValue command. The reason for this is that certtool first
 179 tries to use 20 zero bytes for the SRK password and only then prompts for
 180 and uses the required SRK password. The GnuTLS tpmtool does not support 20
 181 zero bytes for the SRK password, so forces the usage of a 'real' password.
 182
 183 The effect of the authentication failures may be that the TPM CA cannot sign
 184 certificates since the TPM does not accept authenticated commands.
 185
 186 =head1 SEE ALSO
 187
 188 B<swtpm_localca>, B<swtpm-localca.conf>, B<tcsd>
 189
 190 =head1 REPORTING BUGS
 191
 192 Report bugs to Stefan Berger <stefanb@linux.ibm.com>