.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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 .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "swtpm-create-tpmca 8" .TH swtpm-create-tpmca 8 "2022-08-22" "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 [\s-1OPTIONS\s0]\fR .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBswtpm-create-tpmca\fR is a tool to create a \s-1TPM 1.2\s0 based \s-1CA\s0 that can be used by \fBswtpm_localca\fR to sign \s-1EK\s0 and platform certificates. The \s-1CA\s0 uses a GnuTLS key to sign certificates. To do this, GnuTLS talks to the \s-1TPM 1.2\s0 using the \fBtcsd\fR (TrouSerS) daemon. .PP Since the \s-1TPM CA\s0's certificate must be signed by a \s-1CA,\s0 a root certificate authority will also be created and will sign this certificate. The root \s-1CA\s0'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 \&\s-1SWTPM_ROOTCA_PASSWORD\s0 can be set for the password of the root \s-1CA\s0'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 \s-1CA\s0 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 \s-1CA\s0 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 \s-1TCSD.\s0 For the key to be available for signing, the same user that created the \s-1TPM CA\s0 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 \s-1SRK.\s0 .IP "\fB\-\-srk\-password s\fR" 4 .IX Item "--srk-password s" The \s-1TPM SRK\s0 password. .Sp Note: Since GnuTLS tpmtool does not support the 'well known' password of 20 zero bytes, the \s-1SRK\s0 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 \s-1TCP\s0 port on which tcsd is listening for messages. The default port is 30003. .IP "\fB\-\-tpm2\fR" 4 .IX Item "--tpm2" The \s-1TPM\s0 to use for signing the certificates is a \s-1TPM 2\s0 and Intel's \s-1TSS\s0 stack must be running (tpm2\-abrmd) along with its \s-1PKCS11\s0 module. The \s-1TPM 2 PKCS11\s0 module must have been initialized using the tpm2_ptool. .Sp The environment variables \s-1SWTPM_PKCS11_PIN\s0 and \s-1SWTPM_PKCS11_SO_PIN\s0 should be set to hold the PINs. If \s-1SWTPM_PKCS11_PIN\s0 is not set then the default \s-1PIN\s0 \&'swtpm\-tpmca' will be used. \s-1SWTPM_PKCS11_SO_PIN\s0 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 \s-1TPM CA\s0 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 \s-1TPM\s0 is a \s-1TPM 1.2,\s0 we need to start the tcsd first and can then create the \s-1TPM\s0 key and \s-1TPM CA\s0 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 \s-1TPM\s0 is a \s-1TPM 2\s0 and Intel's \s-1TPM 2\s0 stack is installed, we need to start tpm2\-abrmd first and can then create the \s-1TPM\s0 key and \s-1TPM CA\s0 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 \s-1TPM\s0 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 \s-1TPM\s0 for which the certificate is created is a \s-1TPM 2.\s0 .SH "KNOWN ISSUES" .IX Header "KNOWN ISSUES" The interaction of GnuTLS certtool with the \s-1TPM TCSD\s0 daemon may cause so many \s-1TPM\s0 (key) authentication failures that the \s-1TPM\s0 refuses to accept any more authenticated commands until the \s-1TPM\s0'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 \s-1SRK\s0 password and only then prompts for and uses the required \s-1SRK\s0 password. The GnuTLS tpmtool does not support 20 zero bytes for the \s-1SRK\s0 password, so forces the usage of a 'real' password. .PP The effect of the authentication failures may be that the \s-1TPM CA\s0 cannot sign certificates since the \s-1TPM\s0 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