From 55caf3716f32cd67bbfa668956391ce129a128d2 Mon Sep 17 00:00:00 2001 From: Stefan Berger Date: Sun, 27 May 2018 20:01:55 -0400 Subject: [PATCH] manpages: Extend swtpm_setup man page with example for non-root user Extend the swtpm_setup man page with an example for how a non-root user can create a TPM 2 with an EK and platform certificate. Document the default locations of the config file swtpm_setup uses. Signed-off-by: Stefan Berger --- man/man8/swtpm_setup.8 | 81 ++++++++++++++++++++++++++++++++-------- man/man8/swtpm_setup.pod | 47 +++++++++++++++++++++++ 2 files changed, 113 insertions(+), 15 deletions(-) diff --git a/man/man8/swtpm_setup.8 b/man/man8/swtpm_setup.8 index 247f270..76d7f1e 100644 --- a/man/man8/swtpm_setup.8 +++ b/man/man8/swtpm_setup.8 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.31) +.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== @@ -46,7 +46,7 @@ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" -.\" If the F register is turned on, we'll generate index entries on stderr for +.\" 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. @@ -54,20 +54,16 @@ .\" 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 .nr F 0 +.if \nF>0 \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" .. -. if !\nF==2 \{ -. nr % 0 -. nr F 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. @@ -133,7 +129,7 @@ .\" ======================================================================== .\" .IX Title "swtpm_setup 8" -.TH swtpm_setup 8 "2018-04-21" "swtpm" "" +.TH swtpm_setup 8 "2018-05-29" "swtpm" "" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -159,6 +155,11 @@ Use this userid to run swtpm_setup.sh; by default 'tss' is used. .IX Item "--config " Path to configuration file containing the tool to use for creating certificates; see also \fBswtpm_setup.conf\fR +.Sp +If this parameter is not provided, the default configuration file +/etc/swtpm_setup.conf will be used. If the environment variable +\&\s-1XDG_CONFIG_HOME\s0 is set, the configuration file is assumed to be +\&\f(CW$XDG_CONFIG_HOME\fR/swtpm_setup.conf. .IP "\fB\-\-tpm\-state or \fB\-\-tpmstate " 4 .IX Item "--tpm-state or --tpmstate " Path to a directory where the \s-1TPM\s0's state will be written into; @@ -225,7 +226,7 @@ The logfile to log to. By default logging goes to stdout and stderr. .IX Item "--keyfile " The key file contains an \s-1ASCII\s0 hex key consisting of 32 hex digits with an optional leading '0x'. This is the key to be used by the \s-1TPM\s0 emulator -for encrypting the state of the \s-1TPM. \s0 +for encrypting the state of the \s-1TPM.\s0 .IP "\fB\-\-pwdfile " 4 .IX Item "--pwdfile " The passpharse file contains a passphrase from which the \s-1TPM\s0 emulator @@ -264,6 +265,56 @@ To simulate manufacturing of a \s-1TPM,\s0 one would typically run the following Note: since setting up a \s-1TPM 1.2\s0 relies on the \fItcsd\fR for some of its operations, \&\fBswtpm_setup\fR has to be run as root so that it can invoke the \fItcsd\fR either as root or tss user. +.PP +A normal user can also simulate the manufacturing of a \s-1TPM 2\s0 using the +swtpm-localca plugin. The following example assumes that the user has +set the environment variable \s-1XDG_CONFIG_HOME\s0 as follows (using bash for +example): +.PP +.Vb 1 +\& export XDG_CONFIG_HOME=~/.config +.Ve +.PP +Note: The \s-1XDG_CONFIG_HOME\s0 variable is part of the \s-1XDG\s0 Base Directory +Specification. +.PP +The following configuration files need to be created: +.PP +~/.config/swtpm_setup.conf: +.PP +.Vb 4 +\& # Program invoked for creating certificates +\& create_certs_tool= /usr/share/swtpm/swtpm\-localca +\& create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm\-localca.conf +\& create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm\-localca.options +.Ve +.PP +~/.config/swtpm\-localca.conf: +.PP +.Vb 4 +\& statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm\-localca +\& signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm\-localca/signkey.pem +\& issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm\-localca/issuercert.pem +\& certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm\-localca/certserial +.Ve +.PP +~/.config/swtpm\-localca.options: +.PP +.Vb 3 +\& \-\-platform\-manufacturer Fedora +\& \-\-platform\-version 2.12 +\& \-\-platform\-model QEMU +.Ve +.PP +The following commands now create a \s-1TPM 2\s0 with an \s-1EK\s0 and platform +certificate. The state of the \s-1TPM 2\s0 will be stored in the directory +${\s-1XDG_CONFIG_HOME\s0}/mytpm1. +.PP +.Vb 3 +\& #> mkdir \-p ${XDG_CONFIG_HOME}/mytpm1 +\& #> swtpm_setup \-\-tpm2 \-\-tpmstate ${XDG_CONFIG_HOME}/mytpm1 \e +\& \-\-create\-ek\-cert \-\-create\-platform\-cert \-\-lock\-nvram +.Ve .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBswtpm_setup.conf\fR diff --git a/man/man8/swtpm_setup.pod b/man/man8/swtpm_setup.pod index d8d9bad..eea004a 100644 --- a/man/man8/swtpm_setup.pod +++ b/man/man8/swtpm_setup.pod @@ -27,6 +27,11 @@ Use this userid to run swtpm_setup.sh; by default 'tss' is used. Path to configuration file containing the tool to use for creating certificates; see also B +If this parameter is not provided, the default configuration file +/etc/swtpm_setup.conf will be used. If the environment variable +XDG_CONFIG_HOME is set, the configuration file is assumed to be +$XDG_CONFIG_HOME/swtpm_setup.conf. + =item B<--tpm-state > or B<--tpmstate > Path to a directory where the TPM's state will be written into; @@ -157,6 +162,48 @@ Note: since setting up a TPM 1.2 relies on the I for some of its operation B has to be run as root so that it can invoke the I either as root or tss user. + +A normal user can also simulate the manufacturing of a TPM 2 using the +swtpm-localca plugin. The following example assumes that the user has +set the environment variable XDG_CONFIG_HOME as follows (using bash for +example): + + export XDG_CONFIG_HOME=~/.config + +Note: The XDG_CONFIG_HOME variable is part of the XDG Base Directory +Specification. + +The following configuration files need to be created: + +~/.config/swtpm_setup.conf: + + # Program invoked for creating certificates + create_certs_tool= /usr/share/swtpm/swtpm-localca + create_certs_tool_config = ${XDG_CONFIG_HOME}/swtpm-localca.conf + create_certs_tool_options = ${XDG_CONFIG_HOME}/swtpm-localca.options + +~/.config/swtpm-localca.conf: + + statedir = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca + signingkey = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/signkey.pem + issuercert = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/issuercert.pem + certserial = ${XDG_CONFIG_HOME}/var/lib/swtpm-localca/certserial + +~/.config/swtpm-localca.options: + + --platform-manufacturer Fedora + --platform-version 2.12 + --platform-model QEMU + +The following commands now create a TPM 2 with an EK and platform +certificate. The state of the TPM 2 will be stored in the directory +${XDG_CONFIG_HOME}/mytpm1. + + #> mkdir -p ${XDG_CONFIG_HOME}/mytpm1 + #> swtpm_setup --tpm2 --tpmstate ${XDG_CONFIG_HOME}/mytpm1 \ + --create-ek-cert --create-platform-cert --lock-nvram + + =head1 SEE ALSO B