1tpm2_sign(1)                General Commands Manual               tpm2_sign(1)
2
3
4

NAME

6       tpm2_sign(1) - Sign a hash using the TPM.
7

SYNOPSIS

9       tpm2_sign [OPTIONS]
10

DESCRIPTION

12       tpm2_sign(1)  signs an externally provided hash with the specified sym‐
13       metric or asymmetric signing key.  If keyHandle references a restricted
14       signing key, then validation shall be provided, indicating that the TPM
15       performed the hash of the  data  and  validation  shall  indicate  that
16       hashed data did not start with TPM_GENERATED_VALUE.  The scheme of key‐
17       Handle should not be TPM_ALG_NULL.
18

OPTIONS

20       · -k, –key-handle=KEY_HANDLE:
21
22         Handle of key that will perform signing.
23
24       · -c, –key-context=KEY_CONTEXT_FILE:
25
26         Filename of the key context used for the operation.
27
28       · -P, –pwdk=KEY_PASSWORD:
29
30         Specifies the password of KEY_HANDLE.  Passwords  should  follow  the
31         password formatting standards, see section “Password Formatting”.
32
33       · -g, –halg=HASH_ALGORITHM:
34
35         The  hash  algorithm  used  to digest the message.  Algorithms should
36         follow the “formatting standards, see section”Algorithm  Specifiers“.
37         Also,  see section”Supported Hash Algorithms" for a list of supported
38         hash algorithms.
39
40       · -m, –msg=MSG_FILE:
41
42         The message file, containing the content to be digested.
43
44       · -t, –ticket=TICKET_FILE:
45
46         The ticket file, containning the validation structure, optional.
47
48       · -s, –sig=TICKET_FILE:
49
50         The signature file, records the signature structure.
51
52       · -f, –format
53
54         Format selection for the signature output file.  See section  “Signa‐
55         ture Format Specifiers”.
56
57       · -S, –input-session-handle=SESSION_HANDLE:
58
59         Optional  Input  session  handle from a policy session for authoriza‐
60         tion.
61

COMMON OPTIONS

63       This collection of options are common to many programs and provide  in‐
64       formation that many users may expect.
65
66       · -h,  –help: Display the tools manpage.  This requires the manpages to
67         be installed or on MANPATH, See man(1) for more details.
68
69       · -v, –version: Display version information for  this  tool,  supported
70         tctis and exit.
71
72       · -V,  –verbose:  Increase  the information that the tool prints to the
73         console during its execution.  When using this option  the  file  and
74         line number are printed.
75
76       · -Q, –quiet: Silence normal tool output to stdout.
77
78       · -Z,  –enable-errata: Enable the application of errata fixups.  Useful
79         if an errata fixup needs to be applied to commands sent to  the  TPM.
80         # TCTI ENVIRONMENT
81
82       This  collection of environment variables that may be used to configure
83       the various TCTI modules available.
84
85       The values passed through  these  variables  can  be  overridden  on  a
86       per-command basis using the available command line options, see the TC‐
87       TI_OPTIONS section.
88
89       The variables respected depend on how the software was configured.
90
91       · TPM2TOOLS_TCTI_NAME: Select the TCTI used for communication with  the
92         next  component down the TSS stack.  In most configurations this will
93         be the TPM but it could be a simulator or proxy.  The  current  known
94         TCTIs are:
95
96         · tabrmd    -    The    new    resource    manager,   called   tabrmd
97           (https://github.com/01org/tpm2-abrmd).
98
99         · socket - Typically used with the old resource manager,  or  talking
100           directly to a simulator.
101
102         · device - Used when talking directly to a TPM device file.
103
104       · TPM2TOOLS_DEVICE_FILE:  When  using  the device TCTI, specify the TPM
105         device file.  The default is “/dev/tpm0”.
106
107         Note: Using the tpm directly requires the users to ensure  that  con‐
108         current access does not occur and that they manage the tpm resources.
109         These tasks are usually managed by a resource  manager.   Linux  4.12
110         and  greater  supports an in kernel resource manager at “/dev/tpmrm”,
111         typically “/dev/tpmrm0”.
112
113       · TPM2TOOLS_SOCKET_ADDRESS: When using the socket TCTI, specify the do‐
114         main name or IP address used.  The default is 127.0.0.1.
115
116       · TPM2TOOLS_SOCKET_PORT:  When  using the socket TCTI, specify the port
117         number used.  The default is 2321.
118

TCTI OPTIONS

120       This collection of options are used to configure the varous  TCTI  mod‐
121       ules available.  They override any environment variables.
122
123       · -T, –tcti=TCTI_NAME[:TCTI_OPTIONS]: Select the TCTI used for communi‐
124         cation with the next component down the TSS stack.  In most  configu‐
125         rations    this    will    be    the    resource    manager:   tabrmd
126         (https://github.com/01org/tpm2-abrmd) Optionally, tcti  specific  op‐
127         tions can appended to TCTI_NAME by appending a : to TCTI_NAME.
128
129         · For the device TCTI, the TPM device file for use by the device TCTI
130           can be specified.  The  default  is  /dev/tpm0.   Example:  -T  de‐
131           vice:/dev/tpm0
132
133         · For  the socket TCTI, the domain name or IP address and port number
134           used by the socket can be specified.  The default are 127.0.0.1 and
135           2321.  Example: -T socket:127.0.0.1:2321
136
137         · For the abrmd TCTI, it takes no options.  Example: -T abrmd
138

Password Formatting

140       Passwords  are  interpreted  in  two  forms,  string and hex-string.  A
141       string password is not interpreted, and is directly used for authoriza‐
142       tion.   A  hex-string, is converted from a hexidecimal form into a byte
143       array form, thus allowing passwords with non-printable and/or  terminal
144       un-friendly characters.
145
146       By  default  passwords  are assumed to be in the string form.  Password
147       form is specified with special prefix values, they are:
148
149       · str: - Used to indicate it is a raw string.  Useful  for  escaping  a
150         password that starts with the “hex:” prefix.
151
152       · hex: - Used when specifying a password in hex string format.
153

Supported Hash Algorithms

155       Supported hash algorithms are:
156
157       · 0x4 or sha1 for TPM_ALG_SHA1 (default)
158
159       · 0xB or sha256 for TPM_ALG_SHA256
160
161       · 0xC or sha384 for TPM_ALG_SHA384
162
163       · 0xD or sha512 for TPM_ALG_SHA512
164
165       · 0x12 or sm3_256 for TPM_ALG_SM3_256
166
167       NOTE: Your TPM may not support all algorithms.
168

Algorithm Specfiers

170       Options  that  take  algorithms support “nice-names”.  Nice names, like
171       sha1 can be used in place of the raw hex for sha1: 0x4.  The nice names
172       are converted by stripping the leading TPM_ALG_ from the Algorithm Name
173       field and converting it to lower case.  For  instance  TPM_ALG_SHA3_256
174       becomes sha3_256.
175
176       The  algorithms can be found at: <https://trustedcomputinggroup.org/wp-
177       content/uploads/TCG_Algorithm_Registry_Rev_1.24.pdf>
178

Signature Format Specifiers

180       Format selection for the signature output file.  tss (the default) will
181       output a binary blob according to the TPM 2.0 specification and any po‐
182       tential compiler padding.  The option plain will output the plain  sig‐
183       nature data as defined by the used cryptographic algorithm.  # EXAMPLES
184
185              tpm2_sign -k 0x81010001 -P abc123 -g sha256 -m <filePath> -s <filePath> -t <filePath>
186              tpm2_sign -c key.context -P abc123 -g sha256 -m <filePath> -s <filePath> -t <filePath>
187

RETURNS

189       0 on success or 1 on failure.
190

BUGS

192       Github Issues (https://github.com/01org/tpm2-tools/issues)
193

HELP

195       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
196
197
198
199tpm2-tools                      SEPTEMBER 2017                    tpm2_sign(1)