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] [ARGUMENT]
10

DESCRIPTION

12       tpm2_sign(1)  -  Signs  an externally provided message or hash with the
13       specified symmetric or asymmetric signing key.
14
15       If the signing key is a restricted signing key, then validation can  be
16       provided  via  the  -t  output.  The ticket indicates that the TPM per‐
17       formed the hash of the message.
18

OPTIONS

20       · -c, --key-context=OBJECT:
21
22         Context object pointing to the the key used for  signing.   Either  a
23         file or a handle number.  See section "Context Object Format".
24
25       · -p, --authAUTH:
26
27         Optional  authorization value to use the key specified by -c.  Autho‐
28         rization values should follow  the  "authorization  formatting  stan‐
29         dards", see section "Authorization Formatting".
30
31       · -g, --hash-algorithm=ALGORITHM:
32
33         The  hash  algorithm  used  to digest the message.  Algorithms should
34         follow the "formatting  standards",  see  section  "Algorithm  Speci‐
35         fiers".   Also, see section "Supported Hash Algorithms" for a list of
36         supported hash algorithms.
37
38       · -s, --scheme=ALGORITHM:
39
40         The signing scheme used to  sign  the  message.   Optional.   Signing
41         schemes  should follow the "formatting standards", see section "Algo‐
42         rithm Specifiers".  Also, see section "Supported Signing Schemes" for
43         a  list  of supported signature schemes.  If specified, the signature
44         scheme must match the key type.  If left unspecified, a default  sig‐
45         nature scheme for the key type will be used.
46
47       · -d, --digest:
48
49         Indicate  that  FILE  is a file containing the digest of the message.
50         When this option and -t is specified, a warning is generated and  the
51         validation  ticket  (-t)  is  ignored.  You cannot use this option to
52         sign a digest against a restricted signing key.
53
54       · -t, --ticket=FILE:
55
56         The ticket file, containing the validation structure, optional.
57
58       · -o, --signature=FILE:
59
60         The signature file, records the signature structure.
61
62       · -f, --format=FORMAT:
63
64         Format selection for the signature output file.  See section  "Signa‐
65         ture Format Specifiers".
66
67       · ARGUMENT the command line argument specifies the file data for sign.
68
69   References

Context Object Format

71       The  type  of a context object, whether it is a handle or file name, is
72       determined according to the following logic in-order:
73
74       · If the argument is a file path, then the file is loaded as a restored
75         TPM transient object.
76
77       · If the argument is a prefix match on one of:
78
79         · owner: the owner hierarchy
80
81         · platform: the platform hierarchy
82
83         · endorsement: the endorsement hierarchy
84
85         · lockout: the lockout control persistent object
86
87       · If  the  argument argument can be loaded as a number it will be treat
88         as a handle, e.g.  0x81010013 and used directly.OBJECT.
89

Authorization Formatting

91       Authorization for use of an object in TPM2.0 can come  in  3  different
92       forms: 1.  Password 2.  HMAC 3.  Sessions
93
94       NOTE:  "Authorizations  default  to  the EMPTY PASSWORD when not speci‐
95       fied".
96
97   Passwords
98       Passwords are interpreted in the following  forms  below  using  prefix
99       identifiers.
100
101       Note:  By  default  passwords are assumed to be in the string form when
102       they do not have a prefix.
103
104   String
105       A string password, specified by prefix  "str:"  or  it's  absence  (raw
106       string without prefix) is not interpreted, and is directly used for au‐
107       thorization.
108
109   Examples
110              foobar
111              str:foobar
112
113   Hex-string
114       A hex-string password, specified by prefix "hex:" is converted  from  a
115       hexidecimal  form  into a byte array form, thus allowing passwords with
116       non-printable and/or terminal un-friendly characters.
117
118   Example
119              hex:0x1122334455667788
120
121   File
122       A file based password, specified be prefix "file:" should be  the  path
123       of  a  file  containing the password to be read by the tool or a "-" to
124       use stdin.  Storing passwords in files  prevents  information  leakage,
125       passwords passed as options can be read from the process list or common
126       shell history features.
127
128   Examples
129              # to use stdin and be prompted
130              file:-
131
132              # to use a file from a path
133              file:path/to/password/file
134
135              # to echo a password via stdin:
136              echo foobar | tpm2_tool -p file:-
137
138              # to use a bash here-string via stdin:
139
140              tpm2_tool -p file:- <<< foobar
141
142   Sessions
143       When using a policy session to authorize the use of an  object,  prefix
144       the  option argument with the session keyword.  Then indicate a path to
145       a session file that was created with tpm2_startauthsession(1).  Option‐
146       ally, if the session requires an auth value to be sent with the session
147       handle (eg policy password), then append a + and a string as  described
148       in the Passwords section.
149
150   Examples
151       To use a session context file called session.ctx.
152
153              session:session.ctx
154
155       To use a session context file called session.ctx AND send the authvalue
156       mypassword.
157
158              session:session.ctx+mypassword
159
160       To use a session context file called session.ctx AND send the HEX auth‐
161       value 0x11223344.
162
163              session:session.ctx+hex:11223344
164
165   PCR Authorizations
166       You  can satisfy a PCR policy using the "pcr:" prefix and the PCR mini‐
167       language.      The     PCR     minilanguage     is     as      follows:
168       <pcr-spec>=<raw-pcr-file>
169
170       The PCR spec is documented in in the section "PCR bank specifiers".
171
172       The  raw-pcr-file  is an optional the output of the raw PCR contents as
173       returned by tpm2_pcrread(1).
174
175       PCR bank specifiers (common/pcr.md)
176
177   Examples
178       To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifi‐
179       er of:
180
181              pcr:sha256:0,1,2,3
182
183       specifying AUTH.
184

Algorithm Specifiers

186       Options that take algorithms support "nice-names".
187
188       There  are two major algorithm specification string classes, simple and
189       complex.  Only certain algorithms will be accepted by the TPM, based on
190       usage and conditions.
191
192   Simple specifiers
193       These are strings with no additional specification data.  When creating
194       objects, non-specified portions of an object are assumed  to  defaults.
195       You can find the list of known "Simple Specifiers Below".
196
197   Asymmetric
198       · rsa
199
200       · ecc
201
202   Symmetric
203       · aes
204
205       · camellia
206
207   Hashing Algorithms
208       · sha1
209
210       · sha256
211
212       · sha384
213
214       · sha512
215
216       · sm3_256
217
218       · sha3_256
219
220       · sha3_384
221
222       · sha3_512
223
224   Keyed Hash
225       · hmac
226
227       · xor
228
229   Signing Schemes
230       · rsassa
231
232       · rsapss
233
234       · ecdsa
235
236       · ecdaa
237
238       · ecschnorr
239
240   Asymmetric Encryption Schemes
241       · oaep
242
243       · rsaes
244
245       · ecdh
246
247   Modes
248       · ctr
249
250       · ofb
251
252       · cbc
253
254       · cfb
255
256       · ecb
257
258   Misc
259       · null
260
261   Complex Specifiers
262       Objects,  when  specified  for creation by the TPM, have numerous algo‐
263       rithms to populate in the public data.  Things like  type,  scheme  and
264       asymmetric  details,  key  size,  etc.  Below is the general format for
265       specifying this data: <type>:<scheme>:<symmetric-details>
266
267   Type Specifiers
268       This portion of the complex algorithm specifier is required.   The  re‐
269       maining  scheme  and  symmetric  details will default based on the type
270       specified and the type of the object being created.
271
272       · aes - Default AES: aes128
273
274       · aes128<mode> - 128 bit AES with optional mode  (ctr|ofb|cbc|cfb|ecb).
275         If mode is not specified, defaults to null.
276
277       · aes192<mode> - Same as aes128<mode>, except for a 192 bit key size.
278
279       · aes256<mode> - Same as aes128<mode>, except for a 256 bit key size.
280
281       · ecc - Elliptical Curve, defaults to ecc256.
282
283       · ecc192 - 192 bit ECC
284
285       · ecc224 - 224 bit ECC
286
287       · ecc256 - 256 bit ECC
288
289       · ecc384 - 384 bit ECC
290
291       · ecc521 - 521 bit ECC
292
293       · rsa - Default RSA: rsa2048
294
295       · rsa1024 - RSA with 1024 bit keysize.
296
297       · rsa2048 - RSA with 2048 bit keysize.
298
299       · rsa4096 - RSA with 4096 bit keysize.
300
301   Scheme Specifiers
302       Next, is an optional field, it can be skipped.
303
304       Schemes  are  usually Signing Schemes or Asymmetric Encryption Schemes.
305       Most signing schemes take a hash algorithm directly following the sign‐
306       ing  scheme.   If the hash algorithm is missing, it defaults to sha256.
307       Some take no arguments, and some take multiple arguments.
308
309   Hash Optional Scheme Specifiers
310       These scheme specifiers are followed by a dash and a valid  hash  algo‐
311       rithm, For example: oaep-sha256.
312
313       · oaep
314
315       · ecdh
316
317       · rsassa
318
319       · rsapss
320
321       · ecdsa
322
323       · ecschnorr
324
325   Multiple Option Scheme Specifiers
326       This  scheme  specifier  is  followed by a count (max size UINT16) then
327       folloed by a dash(-) and a valid hash algorithm.  * ecdaa For  example,
328       ecdaa4-sha256.  If no count is specified, it defaults to 4.
329
330   No Option Scheme Specifiers
331       This scheme specifier takes NO arguments.  * rsaes
332
333   Symmetric Details Specifiers
334       This  field is optional, and defaults based on the type of object being
335       created and it's attributes.  Generally, any valid Symmetric  specifier
336       from  the Type Specifiers list should work.  If not specified, an asym‐
337       metric objects symmetric details defaults to aes128cfb.
338
339   Examples
340   Create an rsa2048 key with an rsaes asymmetric encryption scheme
341       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r key.priv
342
343   Create an ecc256 key with an ecdaa signing scheme with a count of 4
344       and sha384 hash
345
346       /tpm2_create -C parent.ctx -G ecc256:ec‐
347       daa4-sha384 -u key.pub -r key.priv cryptographic algorithms ALGORITHM.
348

COMMON OPTIONS

350       This  collection of options are common to many programs and provide in‐
351       formation that many users may expect.
352
353       · -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
354         attempts  to  invoke  the  manpager for the tool, however, on failure
355         will output a short tool summary.  This is the same behavior  if  the
356         "man"  option argument is specified, however if explicit "man" is re‐
357         quested, the tool will provide errors from man  on  stderr.   If  the
358         "no-man"  option  if  specified, or the manpager fails, the short op‐
359         tions will be output to stdout.
360
361         To successfully use the manpages feature requires the manpages to  be
362         installed or on MANPATH, See man(1) for more details.
363
364       · -v,  --version:  Display version information for this tool, supported
365         tctis and exit.
366
367       · -V, --verbose: Increase the information that the tool prints  to  the
368         console  during  its  execution.  When using this option the file and
369         line number are printed.
370
371       · -Q, --quiet: Silence normal tool output to stdout.
372
373       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
374         if  an  errata fixup needs to be applied to commands sent to the TPM.
375         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
376         formation many users may expect.
377

TCTI Configuration

379       The  TCTI  or  "Transmission  Interface" is the communication mechanism
380       with the TPM.  TCTIs can be changed for communication with TPMs  across
381       different mediums.
382
383       To control the TCTI, the tools respect:
384
385       1. The command line option -T or --tcti
386
387       2. The environment variable: TPM2TOOLS_TCTI.
388
389       Note:  The  command  line option always overrides the environment vari‐
390       able.
391
392       The current known TCTIs are:
393
394       · tabrmd     -     The     resource     manager,     called      tabrmd
395         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
396         abrmd as a tcti name are synonymous.
397
398       · mssim - Typically used for communicating to the TPM software  simula‐
399         tor.
400
401       · device - Used when talking directly to a TPM device file.
402
403       · none  - Do not initalize a connection with the TPM.  Some tools allow
404         for off-tpm options and thus support not using a TCTI.  Tools that do
405         not  support  it  will error when attempted to be used without a TCTI
406         connection.  Does not support ANY options and MUST  BE  presented  as
407         the exact text of "none".
408
409       The  arguments  to  either  the  command line option or the environment
410       variable are in the form:
411
412       <tcti-name>:<tcti-option-config>
413
414       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
415       tion-config> results in the default being used for that portion respec‐
416       tively.
417
418   TCTI Defaults
419       When a TCTI is not specified, the default TCTI is  searched  for  using
420       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
421       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
422       what TCTI will be chosen as the default by using the -v option to print
423       the version information.  The "default-tcti" key-value pair will  indi‐
424       cate which of the aforementioned TCTIs is the default.
425
426   Custom TCTIs
427       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
428       tools internally use dlopen(3), and the raw tcti-name value is used for
429       the lookup.  Thus, this could be a path to the shared library, or a li‐
430       brary name as understood by dlopen(3) semantics.
431

TCTI OPTIONS

433       This collection of options are used to configure the various known TCTI
434       modules available:
435
436       · device: For the device TCTI, the TPM character device file for use by
437         the device TCTI can be specified.  The default is /dev/tpm0.
438
439         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
440         vice:/dev/tpm0"
441
442       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
443         number used by the simulator  can  be  specified.   The  default  are
444         127.0.0.1 and 2321.
445
446         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
447         TI="mssim:host=localhost,port=2321"
448
449       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
450         ries  of  simple  key value pairs separated by a ',' character.  Each
451         key and value string are separated by a '=' character.
452
453         · TCTI abrmd supports two keys:
454
455           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
456              string).
457
458           2. 'bus_type' : The type of the dbus instance (a string) limited to
459              'session' and 'system'.
460
461         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
462         ample.FooBar:
463
464         \--tcti=tabrmd:bus_name=com.example.FooBar
465
466         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
467         sion:
468
469         \--tcti:bus_type=session
470
471         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
472         ules.  # Signature Format Specifiers
473
474       Format selection for the signature output file.  tss (the default) will
475       output a binary blob according to the TPM 2.0 specification and any po‐
476       tential  compiler padding.  The option plain will output the plain sig‐
477       nature data as defined by the used cryptographic algorithm.
478

EXAMPLES

480   Sign and verify with the TPM using the endorsement
481       hierarchy
482
483              tpm2_createprimary -C e -c primary.ctx
484
485              tpm2_create -G rsa -u rsa.pub -r rsa.priv -C primary.ctx
486
487              tpm2_load -C primary.ctx -u rsa.pub -r rsa.priv -c rsa.ctx
488
489              echo "my message" > message.dat
490
491              tpm2_sign -c rsa.ctx -g sha256 -o sig.rssa message.dat
492
493              tpm2_verifysignature -c rsa.ctx -g sha256 -s sig.rssa -m message.dat
494
495   Sign with the TPM and verify with OSSL
496              openssl ecparam -name prime256v1 -genkey -noout -out private.ecc.pem
497
498              openssl ec -in private.ecc.pem -out public.ecc.pem -pubout
499
500              # Generate a hash to sign
501              echo "data to sign" > data.in.raw
502
503              sha256sum data.in.raw | awk '{ print "000000 " $1 }' | \
504              xxd -r -c 32 > data.in.digest
505
506              # Load the private key for signing
507              tpm2_loadexternal -Q -G ecc -r private.ecc.pem -c key.ctx
508
509              # Sign in the TPM and verify with OSSL
510              tpm2_sign -Q -c key.ctx -g sha256 -d -f plain -o data.out.signed data.in.digest
511
512              openssl dgst -verify public.ecc.pem -keyform pem -sha256 \
513              -signature data.out.signed data.in.raw
514

Returns

516       Tools can return any of the following codes:
517
518       · 0 - Success.
519
520       · 1 - General non-specific error.
521
522       · 2 - Options handling error.
523
524       · 3 - Authentication error.
525
526       · 4 - TCTI related error.
527
528       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
529

BUGS

531       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
532

HELP

534       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
535
536
537
538tpm2-tools                                                        tpm2_sign(1)
Impressum