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

NAME

6       tpm2_nvcertify(1)  -  Provides attestation of the contents of an NV in‐
7       dex.
8

SYNOPSIS

10       tpm2_nvcertify [OPTIONS] [ARGUMENTS]
11

DESCRIPTION

13       tpm2_nvcertify(1) - Provides attestation of the contents of an  NV  in‐
14       dex.   NOTE:  As  part of the attestation output, the NV index contents
15       are revealed.
16

OPTIONS

18       These options control the certification:
19
20       · -C, --signingkey-context=OBJECT:
21
22         The key object that signs the attestation structure.
23
24       · -P, --signingkey-auth=AUTH:
25
26         The authorization value provided for the object specified with -C.
27
28       · -c, --nvauthobj-context=OBJECT:
29
30         The object that is the authorization handle for the NV object.  It is
31         either  the  NV  index handle itself or the platform/ owner hierarchy
32         handle.  If not specified it defaults to the NV index handle.
33
34       · -p, --nvauthobj-auth=AUTH:
35
36         The authorization value provided for the object specified with -c.
37
38       · -g, --hash-algorithm=ALGORITHM:
39
40         The hash algorithm to use in signature generation.
41
42       · -s, --scheme=ALGORITHM:
43
44         The signing scheme used to sign the attestation data.
45
46       · -f, --format=FORMAT:
47
48         Format selection for the signature output file.
49
50       · -o, --signature=FILE:
51
52         Output file name for the signature data.
53
54       · -q, --qualification=FILE_OR_HEX_STR:
55
56         Optional, the policy qualifier data that the signer can choose to in‐
57         clude in the signature.  Can be either a hex string or path.
58
59       · --size=NATURAL_NUMBER:
60
61         Specifies  the  size  of data to be read in bytes, starting from 0 if
62         offset is not specified.  If not specified, the size of the  data  as
63         reported by the public portion of the index will be used.
64
65       · --offset=NATURAL_NUMBER:
66
67         The offset within the NV index to start reading from.
68
69       · --attestation=FILE:
70
71         The attestation data of the type TPM2_CREATION_INFO signed with sign‐
72         ing key.
73
74       · --cphash=FILE
75
76         File path to record the hash of the command parameters.  This is com‐
77         monly termed as cpHash.  NOTE: When this option is selected, The tool
78         will not actually execute the command, it simply returns a cpHash.
79
80       · ARGUMENT the command line argument specifies the NV index  or  offset
81         number.
82
83   References

Context Object Format

85       The  type  of a context object, whether it is a handle or file name, is
86       determined according to the following logic in-order:
87
88       · If the argument is a file path, then the file is loaded as a restored
89         TPM transient object.
90
91       · If the argument is a prefix match on one of:
92
93         · owner: the owner hierarchy
94
95         · platform: the platform hierarchy
96
97         · endorsement: the endorsement hierarchy
98
99         · lockout: the lockout control persistent object
100
101       · If  the  argument argument can be loaded as a number it will be treat
102         as a handle, e.g.  0x81010013 and used directly.OBJECT.
103

Authorization Formatting

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

Algorithm Specifiers

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

Signature Format Specifiers

364       Format selection for the signature output file.  tss (the default) will
365       output a binary blob according to the TPM 2.0 specification and any po‐
366       tential  compiler padding.  The option plain will output the plain sig‐
367       nature data as defined by the used cryptographic algorithm.   signature
368       FORMAT.
369

COMMON OPTIONS

371       This  collection of options are common to many programs and provide in‐
372       formation that many users may expect.
373
374       · -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
375         attempts  to  invoke  the  manpager for the tool, however, on failure
376         will output a short tool summary.  This is the same behavior  if  the
377         "man"  option argument is specified, however if explicit "man" is re‐
378         quested, the tool will provide errors from man  on  stderr.   If  the
379         "no-man"  option  if  specified, or the manpager fails, the short op‐
380         tions will be output to stdout.
381
382         To successfully use the manpages feature requires the manpages to  be
383         installed or on MANPATH, See man(1) for more details.
384
385       · -v,  --version:  Display version information for this tool, supported
386         tctis and exit.
387
388       · -V, --verbose: Increase the information that the tool prints  to  the
389         console  during  its  execution.  When using this option the file and
390         line number are printed.
391
392       · -Q, --quiet: Silence normal tool output to stdout.
393
394       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
395         if  an  errata fixup needs to be applied to commands sent to the TPM.
396         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
397         formation many users may expect.
398

TCTI Configuration

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

TCTI OPTIONS

454       This collection of options are used to configure the various known TCTI
455       modules available:
456
457       · device: For the device TCTI, the TPM character device file for use by
458         the device TCTI can be specified.  The default is /dev/tpm0.
459
460         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
461         vice:/dev/tpm0"
462
463       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
464         number used by the simulator  can  be  specified.   The  default  are
465         127.0.0.1 and 2321.
466
467         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
468         TI="mssim:host=localhost,port=2321"
469
470       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
471         ries  of  simple  key value pairs separated by a ',' character.  Each
472         key and value string are separated by a '=' character.
473
474         · TCTI abrmd supports two keys:
475
476           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
477              string).
478
479           2. 'bus_type' : The type of the dbus instance (a string) limited to
480              'session' and 'system'.
481
482         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
483         ample.FooBar:
484
485         \--tcti=tabrmd:bus_name=com.example.FooBar
486
487         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
488         sion:
489
490         \--tcti:bus_type=session
491
492         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
493         ules.
494

EXAMPLES

496              tpm2_nvdefine -s 32 -a "authread|authwrite" 1
497
498              dd if=/dev/urandom bs=1 count=32 status=none| \
499              tpm2_nvwrite 1 -i-
500
501              tpm2_createprimary -C o -c primary.ctx -Q
502
503              tpm2_create -G rsa -u rsa.pub -r rsa.priv -C primary.ctx -c signing_key.ctx -Q
504
505              tpm2_readpublic -c signing_key.ctx -f pem -o sslpub.pem -Q
506
507              tpm2_nvcertify -C signing_key.ctx -g sha256 -f plain -s rsassa \
508              -o signature.bin --attestation attestation.bin --size 32 1
509

Returns

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

BUGS

526       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
527

HELP

529       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
530
531
532
533tpm2-tools                                                   tpm2_nvcertify(1)
Impressum