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

       --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
	   outfile 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
	   outfile 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
	   'localhost'.

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

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.

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

home | help