1swtpm-create-tpmca(8)                                    swtpm-create-tpmca(8)
2
3
4

NAME

6       swtpm-create-tpmca - Tool to create a local CA for swtpm_localca
7

SYNOPSIS

9       swtpm-create-tpmca [OPTIONS]
10

DESCRIPTION

12       swtpm-create-tpmca is a tool to create a TPM 1.2 based CA that can be
13       used by swtpm_localca to sign EK and platform certificates.  The CA
14       uses a GnuTLS key to sign certificates. To do this, GnuTLS talks to the
15       TPM 1.2 using the tcsd (TrouSerS) daemon.
16
17       Since the TPM CA's certificate must be signed by a CA, a root
18       certificate authority will also be created and will sign this
19       certificate. The root CA's private key and certificate will be located
20       in the same directory as the signing key and have the names
21       swtpm-localca-rootca-privkey.pem and swtpm-localca-rootca-cert.pem
22       respectively. The environment variable SWTPM_ROOTCA_PASSWORD can be set
23       for the password of the root CA's private key.
24
25       Note: This tool is experimental. See the section on known issues below.
26
27       The following options are supported:
28
29       --dir dir
30           The directory where the keys will be written to. An existing root
31           CA with the files swtpm-localca-rootca-privkey.pem and
32           swtpm-localca-rootca-cert.pem in this directory will be reused. If
33           either one of these files does not exist, a new root CA will be
34           created.
35
36       --overwrite
37           Overwrite the contents of the output directory.
38
39       --register
40           Register the key with TCSD. For the key to be available for
41           signing, the same user that created the TPM CA has to run the
42           swtpm_localca tool later on. If this option is not passed, the
43           private key is written into a file and can be used by others as
44           well.
45
46       --key-password s
47           The new signing key will get this password.
48
49           Note: Due to a bug in GnuTLS certtool it may be necessary to use
50           the same password for the signing key as for the SRK.
51
52       --srk-password s
53           The TPM SRK password.
54
55           Note: Since GnuTLS tpmtool does not support the 'well known'
56           password of 20 zero bytes, the SRK password must be set.
57
58       --outfile filename
59           The name of a file where to write the swtpm-localca.conf
60           configuration to.
61
62       --owner owner
63           The name or uid number of the owner who will own the directory and
64           outfile file. This option only has an effect if this swtpm-create-
65           tpmca is run by the root user.
66
67       --group group
68           The name or gid number of the group who will own the directory and
69           outfile file. This option only has an effect if this swtpm-create-
70           tpmca is run by the root user.
71
72       --tss-tcsd-hostname
73           The hostname where tcsd is running on. The default hostname is
74           'localhost'.
75
76       -tss-tcsd-port
77           The TCP port on which tcsd is listening for messages. The default
78           port is 30003.
79
80       --tpm2
81           The TPM to use for signing the certificates is a TPM 2 and Intel's
82           TSS stack must be running (tpm2-abrmd) along with its PKCS11
83           module.  The TPM 2 PKCS11 module must have been initialized using
84           the tpm2_ptool.
85
86           The environment variables SWTPM_PKCS11_PIN and SWTPM_PKCS11_SO_PIN
87           should be set to hold the PINs. If SWTPM_PKCS11_PIN is not set then
88           the default PIN 'swtpm-tpmca' will be used. SWTPM_PKCS11_SO_PIN is
89           needed for creating the token and must be explicitly set as an
90           environment variable.
91
92       --pid pimary-object-id
93           The primary object id that the tpm2_ptool returns upon 'init'.
94
95       -help, -h, -?
96           Display the help screen and exit.
97

EXAMPLE

99       The following example creates an intermediate TPM CA and writes the
100       keys into /var/lib/swtpm-localca and the swtpm_localca configuration to
101       /etc/swtpm-localca.conf. It can then be used for signing certificates
102       of newly created swtpm TPMs.
103
104       If the host's TPM is a TPM 1.2, we need to start the tcsd first and can
105       then create the TPM key and TPM CA certificate:
106
107        #> sudo systemctl start tcsd
108        #> sudo /usr/share/swtpm/swtpm-create-tpmca \
109                       --dir /var/lib/swtpm-localca \
110                       --overwrite \
111                       --outfile /etc/swtpm-localca.conf \
112                       --srk-password password \
113                       --key-password password \
114                       --group tss
115        statedir = /var/lib/swtpm-localca
116        signingkey = tpmkey:file=/var/lib/swtpm-localca/swtpm-localca-tpmca-privkey.pem
117        issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
118        certserial = /var/lib/swtpm-localca/certserial
119        TSS_TCSD_HOSTNAME = localhost
120        TSS_TCSD_PORT = 30003
121        signingkey_password = password
122        parentkey_password = password
123
124       Alternatively, if the host's TPM is a TPM 2 and Intel's TPM 2 stack is
125       installed, we need to start tpm2-abrmd first and can then create the
126       TPM key and TPM CA certificate:
127
128        #> sudo systemctl start tpm2-abrmd
129        #> tpm2_ptool init
130        action: Created
131        id: 1                   # this is the --pid parameter below
132        #> sudo SWTPM_PKCS11_PIN="mypin 123" SWTPM_PKCS11_SO_PIN=123 /usr/share/swtpm/swtpm-create-tpmca \
133                       --dir /var/lib/swtpm-localca \
134                       --overwrite \
135                       --outfile /etc/swtpm-localca.conf \
136                       --group tss \
137                       --tpm2 \
138                       --pid 1
139        statedir = /var/lib/swtpm-localca
140        signingkey = pkcs11:model=SW%20%20%20TPM\;manufacturer=IBM\;serial=0000000000000000\;token=swtpm-tpmca-1\;id=%31\;object=swtpm-tpmca-key\;type=private
141        issuercert = /var/lib/swtpm-localca/swtpm-localca-tpmca-cert.pem
142        certserial = /var/lib/swtpm-localca/certserial
143        SWTPM_PKCS11_PIN = mypin 123
144
145       Note: This also works for non-root users by adapting the --dir and
146       --outfile parameters here and below by changing the --dir parameter and
147       adding a --config parameter.
148
149       To test either one of the above TPM CAs, run the following command:
150
151        #> swtpm_localca \
152               --type ek --ek x=11,y=13 \
153               --dir /tmp --vmid test --tpm2 \
154               --tpm-spec-family 2.0 --tpm-spec-revision 146 --tpm-spec-level 00 \
155               --tpm-model swtpm --tpm-version 20170101 --tpm-manufacturer IBM
156
157       The --tpm2 in this command indicates that the TPM for which the
158       certificate is created is a TPM 2.
159

KNOWN ISSUES

161       The interaction of GnuTLS certtool with the TPM TCSD daemon may cause
162       so many TPM (key) authentication failures that the TPM refuses to
163       accept any more authenticated commands until the TPM's owner sends it
164       the TPM_ORD_ResetLockValue command. The reason for this is that
165       certtool first tries to use 20 zero bytes for the SRK password and only
166       then prompts for and uses the required SRK password. The GnuTLS tpmtool
167       does not support 20 zero bytes for the SRK password, so forces the
168       usage of a 'real' password.
169
170       The effect of the authentication failures may be that the TPM CA cannot
171       sign certificates since the TPM does not accept authenticated commands.
172

SEE ALSO

174       swtpm_localca, swtpm-localca.conf, tcsd
175

REPORTING BUGS

177       Report bugs to Stefan Berger <stefanb@linux.ibm.com>
178
179
180
181swtpm                             2023-08-16             swtpm-create-tpmca(8)
Impressum