.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "swtpm-create-tpmca 8" .TH swtpm-create-tpmca 8 2024-04-20 swtpm "" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH NAME swtpm\-create\-tpmca \- Tool to create a local CA for swtpm_localca .SH SYNOPSIS .IX Header "SYNOPSIS" \&\fBswtpm-create-tpmca [OPTIONS]\fR .SH DESCRIPTION .IX Header "DESCRIPTION" \&\fBswtpm-create-tpmca\fR is a tool to create a TPM 1.2 based CA that can be used by \fBswtpm_localca\fR 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 \fBtcsd\fR (TrouSerS) daemon. .PP 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. .PP Note: This tool is experimental. See the section on known issues below. .PP The following options are supported: .IP "\fB\-\-dir dir\fR" 4 .IX Item "--dir dir" The directory where the keys will be written to. An existing root CA with the files \fIswtpm\-localca\-rootca\-privkey.pem\fR and \&\fIswtpm\-localca\-rootca\-cert.pem\fR in this directory will be reused. If either one of these files does not exist, a new root CA will be created. .IP \fB\-\-overwrite\fR 4 .IX Item "--overwrite" Overwrite the contents of the output directory. .IP \fB\-\-register\fR 4 .IX Item "--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. .IP "\fB\-\-key\-password s\fR" 4 .IX Item "--key-password s" The new signing key will get this password. .Sp 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. .IP "\fB\-\-srk\-password s\fR" 4 .IX Item "--srk-password s" The TPM SRK password. .Sp Note: Since GnuTLS tpmtool does not support the 'well known' password of 20 zero bytes, the SRK password must be set. .IP "\fB\-\-outfile filename\fR" 4 .IX Item "--outfile filename" The name of a file where to write the swtpm\-localca.conf configuration to. .IP "\fB\-\-owner owner\fR" 4 .IX Item "--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. .IP "\fB\-\-group group\fR" 4 .IX Item "--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. .IP \fB\-\-tss\-tcsd\-hostname\fR 4 .IX Item "--tss-tcsd-hostname" The hostname where tcsd is running on. The default hostname is 'localhost'. .IP \fB\-tss\-tcsd\-port\fR 4 .IX Item "-tss-tcsd-port" The TCP port on which tcsd is listening for messages. The default port is 30003. .IP \fB\-\-tpm2\fR 4 .IX Item "--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. .Sp 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. .IP "\fB\-\-pid pimary-object-id\fR" 4 .IX Item "--pid pimary-object-id" The primary object id that the tpm2_ptool returns upon 'init'. .IP "\fB\-help, \-h, \-?\fR" 4 .IX Item "-help, -h, -?" Display the help screen and exit. .SH EXAMPLE .IX Header "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 \fBswtpm\fR TPMs. .PP 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: .PP .Vb 10 \& #> sudo systemctl start tcsd \& #> sudo /usr/share/swtpm/swtpm\-create\-tpmca \e \& \-\-dir /var/lib/swtpm\-localca \e \& \-\-overwrite \e \& \-\-outfile /etc/swtpm\-localca.conf \e \& \-\-srk\-password password \e \& \-\-key\-password password \e \& \-\-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 .Ve .PP 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: .PP .Vb 10 \& #> 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 \e \& \-\-dir /var/lib/swtpm\-localca \e \& \-\-overwrite \e \& \-\-outfile /etc/swtpm\-localca.conf \e \& \-\-group tss \e \& \-\-tpm2 \e \& \-\-pid 1 \& statedir = /var/lib/swtpm\-localca \& signingkey = pkcs11:model=SW%20%20%20TPM\e;manufacturer=IBM\e;serial=0000000000000000\e;token=swtpm\-tpmca\-1\e;id=%31\e;object=swtpm\-tpmca\-key\e;type=private \& issuercert = /var/lib/swtpm\-localca/swtpm\-localca\-tpmca\-cert.pem \& certserial = /var/lib/swtpm\-localca/certserial \& SWTPM_PKCS11_PIN = mypin 123 .Ve .PP 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. .PP To test either one of the above TPM CAs, run the following command: .PP .Vb 5 \& #> swtpm_localca \e \& \-\-type ek \-\-ek x=11,y=13 \e \& \-\-dir /tmp \-\-vmid test \-\-tpm2 \e \& \-\-tpm\-spec\-family 2.0 \-\-tpm\-spec\-revision 146 \-\-tpm\-spec\-level 00 \e \& \-\-tpm\-model swtpm \-\-tpm\-version 20170101 \-\-tpm\-manufacturer IBM .Ve .PP The \-\-tpm2 in this command indicates that the TPM for which the certificate is created is a TPM 2. .SH "KNOWN ISSUES" .IX Header "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. .PP The effect of the authentication failures may be that the TPM CA cannot sign certificates since the TPM does not accept authenticated commands. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBswtpm_localca\fR, \fBswtpm\-localca.conf\fR, \fBtcsd\fR .SH "REPORTING BUGS" .IX Header "REPORTING BUGS" Report bugs to Stefan Berger