Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
swtpm-create-tpmca(8)					   swtpm-create-tpmca(8)

NAME
     swtpm-create-tpmca - Tool to create a local CA for swtpm_localca

SYNOPSIS
     swtpm-create-tpmca [OPTIONS]

DESCRIPTION
     swtpm-create-tpmca is a tool to create a TPM 1.2 or TPM 2 based CA that can
     be used by swtpm_localca to sign EK and platform certificates.  The CA uses
     a GnuTLS key to sign certificates. If a TPM 1.2 is used then GnuTLS will
     talk to the TPM 1.2 using the tcsd (TrouSerS) daemon.  If a TPM 2 is used
     then the Intel pkcs11 driver and its tools (tpm2_ptool) are also required.

     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:

     --dir dir
	 The directory where the keys will be written to. An existing root CA
	 with the files swtpm-localca-rootca-privkey.pem and swtpm-lo-
	 calca-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.

     --overwrite
	 Overwrite the contents of the output directory.

     --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.

     --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.

     --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.

     --outfile filename
	 The name of a file where to write the swtpm-localca.conf configuration
	 to.

     --owner owner
	 The name or uid number of the owner who will own the directory and out-
	 file file. This option only has an effect if this swtpm-create-tpmca is
	 run by the root user.

     --group group
	 The name or gid number of the group who will own the directory and out-
	 file file. This option only has an effect if this swtpm-create-tpmca is
	 run by the root user.

     --tss-tcsd-hostname
	 The hostname where tcsd is running on. The default hostname is 'local-
	 host'.

     -tss-tcsd-port
	 The TCP port on which tcsd is listening for messages. The default port
	 is 30003.

     --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.

     --pid pimary-object-id
	 The primary object id that the tpm2_ptool returns upon 'init'.

     -help, -h, -?
	 Display the help screen and exit.

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 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 in-
     stalled, we need to start tpm2-abrmd first and can then create the TPM key
     and TPM CA certificate:

      #> sudo systemctl start tpm2-abrmd     # may not be required with recent Intel TPM 2 tools
      #> sudo 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 --out-
     file 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.

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_Re-
     setLockValue 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.

SEE ALSO
     swtpm_localca, swtpm-localca.conf, tcsd

REPORTING BUGS
     Report bugs to Stefan Berger <stefanb@linux.ibm.com>

swtpm				   2025-04-30		   swtpm-create-tpmca(8)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=swtpm-create-tpmca&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>

home | help