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

NAME

6       tpm2_stirrandom(1) - Add "additional information" into TPM RNG state.
7

SYNOPSIS

9       tpm2_stirrandom [OPTIONS] [ARGUMENT]
10

DESCRIPTION

12       tpm2_stirrandom(1)  - Inject "additional information" as bytes into TPM
13       entropy Protected Capability pool.
14
15       "Additional information" can be extracted from file specified as  argu‐
16       ment or being read from STDIN if argument is not specified.
17
18       Up  to  128  bytes  can  be  injected at once through standard input to
19       tpm2_stirrandom(1).
20
21       If input file is larger than 128 bytes, tpm2_stirrandom(1) will fail.
22
23       Adding data through tpm2_stirrandom(1) will trigger a reseeding of  TPM
24       DRBG  Protected  Capability.   It is used when performing any sensitive
25       action on a shielded location such as loading a persistent key or  act‐
26       ing on a Protected Capability like updating TPM firmware.
27

OPTIONS

29       This command has no option
30
31   References

COMMON OPTIONS

33       This  collection of options are common to many programs and provide in‐
34       formation that many users may expect.
35
36       · -h, --help=[man|no-man]: Display the tools manpage.  By  default,  it
37         attempts  to  invoke  the  manpager for the tool, however, on failure
38         will output a short tool summary.  This is the same behavior  if  the
39         "man"  option argument is specified, however if explicit "man" is re‐
40         quested, the tool will provide errors from man  on  stderr.   If  the
41         "no-man"  option  if  specified, or the manpager fails, the short op‐
42         tions will be output to stdout.
43
44         To successfully use the manpages feature requires the manpages to  be
45         installed or on MANPATH, See man(1) for more details.
46
47       · -v,  --version:  Display version information for this tool, supported
48         tctis and exit.
49
50       · -V, --verbose: Increase the information that the tool prints  to  the
51         console  during  its  execution.  When using this option the file and
52         line number are printed.
53
54       · -Q, --quiet: Silence normal tool output to stdout.
55
56       · -Z, --enable-errata: Enable the application of errata fixups.  Useful
57         if  an  errata fixup needs to be applied to commands sent to the TPM.
58         Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent.   in‐
59         formation many users may expect.
60

TCTI Configuration

62       The  TCTI  or  "Transmission  Interface" is the communication mechanism
63       with the TPM.  TCTIs can be changed for communication with TPMs  across
64       different mediums.
65
66       To control the TCTI, the tools respect:
67
68       1. The command line option -T or --tcti
69
70       2. The environment variable: TPM2TOOLS_TCTI.
71
72       Note:  The  command  line option always overrides the environment vari‐
73       able.
74
75       The current known TCTIs are:
76
77       · tabrmd     -     The     resource     manager,     called      tabrmd
78         (https://github.com/tpm2-software/tpm2-abrmd).   Note that tabrmd and
79         abrmd as a tcti name are synonymous.
80
81       · mssim - Typically used for communicating to the TPM software  simula‐
82         tor.
83
84       · device - Used when talking directly to a TPM device file.
85
86       · none  - Do not initalize a connection with the TPM.  Some tools allow
87         for off-tpm options and thus support not using a TCTI.  Tools that do
88         not  support  it  will error when attempted to be used without a TCTI
89         connection.  Does not support ANY options and MUST  BE  presented  as
90         the exact text of "none".
91
92       The  arguments  to  either  the  command line option or the environment
93       variable are in the form:
94
95       <tcti-name>:<tcti-option-config>
96
97       Specifying an empty string for  either  the  <tcti-name>  or  <tcti-op‐
98       tion-config> results in the default being used for that portion respec‐
99       tively.
100
101   TCTI Defaults
102       When a TCTI is not specified, the default TCTI is  searched  for  using
103       dlopen(3)  semantics.   The  tools  will  search for tabrmd, device and
104       mssim TCTIs IN THAT ORDER and USE THE FIRST ONE FOUND.  You  can  query
105       what TCTI will be chosen as the default by using the -v option to print
106       the version information.  The "default-tcti" key-value pair will  indi‐
107       cate which of the aforementioned TCTIs is the default.
108
109   Custom TCTIs
110       Any TCTI that implements the dynamic TCTI interface can be loaded.  The
111       tools internally use dlopen(3), and the raw tcti-name value is used for
112       the lookup.  Thus, this could be a path to the shared library, or a li‐
113       brary name as understood by dlopen(3) semantics.
114

TCTI OPTIONS

116       This collection of options are used to configure the various known TCTI
117       modules available:
118
119       · device: For the device TCTI, the TPM character device file for use by
120         the device TCTI can be specified.  The default is /dev/tpm0.
121
122         Example:   -T   device:/dev/tpm0   or   export    TPM2TOOLS_TCTI="de‐
123         vice:/dev/tpm0"
124
125       · mssim:  For  the  mssim  TCTI, the domain name or IP address and port
126         number used by the simulator  can  be  specified.   The  default  are
127         127.0.0.1 and 2321.
128
129         Example:  -T  mssim:host=localhost,port=2321  or export TPM2TOOLS_TC‐
130         TI="mssim:host=localhost,port=2321"
131
132       · abrmd: For the abrmd TCTI, the configuration string format is  a  se‐
133         ries  of  simple  key value pairs separated by a ',' character.  Each
134         key and value string are separated by a '=' character.
135
136         · TCTI abrmd supports two keys:
137
138           1. 'bus_name' : The name of  the  tabrmd  service  on  the  bus  (a
139              string).
140
141           2. 'bus_type' : The type of the dbus instance (a string) limited to
142              'session' and 'system'.
143
144         Specify the tabrmd tcti name and a config string of  bus_name=com.ex‐
145         ample.FooBar:
146
147         \--tcti=tabrmd:bus_name=com.example.FooBar
148
149         Specify the default (abrmd) tcti and a config string of bus_type=ses‐
150         sion:
151
152         \--tcti:bus_type=session
153
154         NOTE: abrmd and tabrmd are synonymous.  the various known  TCTI  mod‐
155         ules.)
156

EXAMPLES

158   Inject from stdin using echo
159              echo -n "myrandomdata" | tpm2_stirrandom
160
161   Inject 64 bytes from stdin using a file
162              dd if=/dev/urandom bs=1 count=64 > myrandom.bin
163
164              tpm2_stirrandom < ./myrandom.bin
165
166   Inject bytes from a file and reading up to 128 bytes
167              dd if=/dev/urandom of=./myrandom.bin bs=1 count=42
168
169              tpm2_stirrandom ./myrandom.bin
170

NOTES

172       Please  be  aware  that  even  if the "additional information" added by
173       tpm2_stirrandom(1) can be entropy gathered from other DRBG sources, the
174       TPM  has no way of determining if the value has any entropy or not.  As
175       a consequence, it will just be considered as "additional input".
176
177       The   "additional   input"   is   as   defined   in   NIST    SP800-90A
178       (https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublica
179       tion800-90.pdf)
180

Returns

182       Tools can return any of the following codes:
183
184       · 0 - Success.
185
186       · 1 - General non-specific error.
187
188       · 2 - Options handling error.
189
190       · 3 - Authentication error.
191
192       · 4 - TCTI related error.
193
194       · 5 - Non supported scheme.  Applicable to tpm2_testparams.
195

BUGS

197       Github Issues (https://github.com/tpm2-software/tpm2-tools/issues)
198

HELP

200       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)
201
202
203
204tpm2-tools                                                  tpm2_stirrandom(1)
Impressum