diff --git a/man/man1/tpm2_encodeobject.1 b/man/man1/tpm2_encodeobject.1 new file mode 100644 index 00000000..9b616bb0 --- /dev/null +++ b/man/man1/tpm2_encodeobject.1 @@ -0,0 +1,428 @@ +.\" Automatically generated by Pandoc 2.5 +.\" +.TH "tpm2_encodeobject" "1" "" "tpm2\-tools" "General Commands Manual" +.hy +.SH NAME +.PP +\f[B]tpm2_encodeobject\f[R](1) \- Encode an object into a combined PEM +format. +.SH SYNOPSIS +.PP +\f[B]tpm2_encodeobject\f[R] [\f[I]OPTIONS\f[R]] +.SH DESCRIPTION +.PP +\f[B]tpm2_encodeobject\f[R](1) \- Encode both the private and public +portions of an object into a combined PEM format used by +tpm2\-tss\-engine. +.PP +The tool reads private and public portions of an object and encodes it +into a combined PEM format used by tpm2\-tss\-engine and other +applications. +.PP +\f[B]NOTE\f[R]: Both private and public portions of the tpm key must be +specified. +.SH OPTIONS +.IP \[bu] 2 +\f[B]\-C\f[R], \f[B]\-\-parent\-context\f[R]=\f[I]OBJECT\f[R]: +.RS 2 +.PP +The parent object. +.RE +.IP \[bu] 2 +\f[B]\-P\f[R], \f[B]\-\-auth\f[R]=\f[I]AUTH\f[R]: +.RS 2 +.PP +The authorization value of the parent object specified by \f[B]\-C\f[R]. +.RE +.IP \[bu] 2 +\f[B]\-u\f[R], \f[B]\-\-public\f[R]=\f[I]FILE\f[R]: +.RS 2 +.PP +A file containing the public portion of the object. +.RE +.IP \[bu] 2 +\f[B]\-r\f[R], \f[B]\-\-private\f[R]=\f[I]FILE\f[R]: +.RS 2 +.PP +A file containing the sensitive portion of the object. +.RE +.IP \[bu] 2 +\f[B]\-p\f[R], \f[B]\-\-key\-auth\f[R]: +.RS 2 +.PP +Indicates if an authorization value is needed for the object specified +by \f[B]\-r\f[R] and \f[B]\-u\f[R]. +.RE +.IP \[bu] 2 +\f[B]\-o\f[R], \f[B]\-\-output\f[R]=\f[I]FILE\f[R]: +.RS 2 +.PP +The output file path, recording the public portion of the object. +.RE +.SS References +.SH Context Object Format +.PP +The type of a context object, whether it is a handle or file name, is +determined according to the following logic \f[I]in\-order\f[R]: +.IP \[bu] 2 +If the argument is a file path, then the file is loaded as a restored +TPM transient object. +.IP \[bu] 2 +If the argument is a \f[I]prefix\f[R] match on one of: +.RS 2 +.IP \[bu] 2 +owner: the owner hierarchy +.IP \[bu] 2 +platform: the platform hierarchy +.IP \[bu] 2 +endorsement: the endorsement hierarchy +.IP \[bu] 2 +lockout: the lockout control persistent object +.RE +.IP \[bu] 2 +If the argument argument can be loaded as a number it will be treat as a +handle, e.g.\ 0x81010013 and used directly._OBJECT_. +.SH Authorization Formatting +.PP +Authorization for use of an object in TPM2.0 can come in 3 different +forms: 1. +Password 2. +HMAC 3. +Sessions +.PP +\f[B]NOTE:\f[R] \[lq]Authorizations default to the \f[B]EMPTY +PASSWORD\f[R] when not specified\[rq]. +.SS Passwords +.PP +Passwords are interpreted in the following forms below using prefix +identifiers. +.PP +\f[B]Note\f[R]: By default passwords are assumed to be in the string +form when they do not have a prefix. +.SS String +.PP +A string password, specified by prefix \[lq]str:\[rq] or it\[cq]s +absence (raw string without prefix) is not interpreted, and is directly +used for authorization. +.SS Examples +.IP +.nf +\f[C] +foobar +str:foobar +\f[R] +.fi +.SS Hex\-string +.PP +A hex\-string password, specified by prefix \[lq]hex:\[rq] is converted +from a hexidecimal form into a byte array form, thus allowing passwords +with non\-printable and/or terminal un\-friendly characters. +.SS Example +.IP +.nf +\f[C] +hex:1122334455667788 +\f[R] +.fi +.SS File +.PP +A file based password, specified be prefix \[lq]file:\[rq] should be the +path of a file containing the password to be read by the tool or a +\[lq]\-\[rq] to use stdin. +Storing passwords in files prevents information leakage, passwords +passed as options can be read from the process list or common shell +history features. +.SS Examples +.IP +.nf +\f[C] +# to use stdin and be prompted +file:\- + +# to use a file from a path +file:path/to/password/file + +# to echo a password via stdin: +echo foobar | tpm2_tool \-p file:\- + +# to use a bash here\-string via stdin: + +tpm2_tool \-p file:\- <<< foobar +\f[R] +.fi +.SS Sessions +.PP +When using a policy session to authorize the use of an object, prefix +the option argument with the \f[I]session\f[R] keyword. +Then indicate a path to a session file that was created with +tpm2_startauthsession(1). +Optionally, if the session requires an auth value to be sent with the +session handle (eg policy password), then append a + and a string as +described in the \f[B]Passwords\f[R] section. +.SS Examples +.PP +To use a session context file called \f[I]session.ctx\f[R]. +.IP +.nf +\f[C] +session:session.ctx +\f[R] +.fi +.PP +To use a session context file called \f[I]session.ctx\f[R] \f[B]AND\f[R] +send the authvalue mypassword. +.IP +.nf +\f[C] +session:session.ctx+mypassword +\f[R] +.fi +.PP +To use a session context file called \f[I]session.ctx\f[R] \f[B]AND\f[R] +send the \f[I]HEX\f[R] authvalue 0x11223344. +.IP +.nf +\f[C] +session:session.ctx+hex:11223344 +\f[R] +.fi +.SS PCR Authorizations +.PP +You can satisfy a PCR policy using the \[lq]pcr:\[rq] prefix and the PCR +minilanguage. +The PCR minilanguage is as follows: +\f[C]=\f[R] +.PP +The PCR spec is documented in in the section \[lq]PCR bank +specifiers\[rq]. +.PP +The \f[C]raw\-pcr\-file\f[R] is an \f[B]optional\f[R] argument that +contains the output of the raw PCR contents as returned by +\f[I]tpm2_pcrread(1)\f[R]. +.PP +PCR bank specifiers (pcr.md) +.SS Examples +.PP +To satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3 use a specifier +of: +.IP +.nf +\f[C] +pcr:sha256:0,1,2,3 +\f[R] +.fi +.PP +specifying \f[I]AUTH\f[R]. +.SH COMMON OPTIONS +.PP +This collection of options are common to many programs and provide +information that many users may expect. +.IP \[bu] 2 +\f[B]\-h\f[R], \f[B]\-\-help=[man|no\-man]\f[R]: Display the tools +manpage. +By default, it attempts to invoke the manpager for the tool, however, on +failure will output a short tool summary. +This is the same behavior if the \[lq]man\[rq] option argument is +specified, however if explicit \[lq]man\[rq] is requested, the tool will +provide errors from man on stderr. +If the \[lq]no\-man\[rq] option if specified, or the manpager fails, the +short options will be output to stdout. +.RS 2 +.PP +To successfully use the manpages feature requires the manpages to be +installed or on \f[I]MANPATH\f[R], See man(1) for more details. +.RE +.IP \[bu] 2 +\f[B]\-v\f[R], \f[B]\-\-version\f[R]: Display version information for +this tool, supported tctis and exit. +.IP \[bu] 2 +\f[B]\-V\f[R], \f[B]\-\-verbose\f[R]: Increase the information that the +tool prints to the console during its execution. +When using this option the file and line number are printed. +.IP \[bu] 2 +\f[B]\-Q\f[R], \f[B]\-\-quiet\f[R]: Silence normal tool output to +stdout. +.IP \[bu] 2 +\f[B]\-Z\f[R], \f[B]\-\-enable\-errata\f[R]: Enable the application of +errata fixups. +Useful if an errata fixup needs to be applied to commands sent to the +TPM. +Defining the environment TPM2TOOLS_ENABLE_ERRATA is equivalent. +information many users may expect. +.SH TCTI Configuration +.PP +The TCTI or \[lq]Transmission Interface\[rq] is the communication +mechanism with the TPM. +TCTIs can be changed for communication with TPMs across different +mediums. +.PP +To control the TCTI, the tools respect: +.IP "1." 3 +The command line option \f[B]\-T\f[R] or \f[B]\-\-tcti\f[R] +.IP "2." 3 +The environment variable: \f[I]TPM2TOOLS_TCTI\f[R]. +.PP +\f[B]Note:\f[R] The command line option always overrides the environment +variable. +.PP +The current known TCTIs are: +.IP \[bu] 2 +tabrmd \- The resource manager, called +tabrmd (https://github.com/tpm2-software/tpm2-abrmd). +Note that tabrmd and abrmd as a tcti name are synonymous. +.IP \[bu] 2 +mssim \- Typically used for communicating to the TPM software simulator. +.IP \[bu] 2 +device \- Used when talking directly to a TPM device file. +.IP \[bu] 2 +none \- Do not initalize a connection with the TPM. +Some tools allow for off\-tpm options and thus support not using a TCTI. +Tools that do not support it will error when attempted to be used +without a TCTI connection. +Does not support \f[I]ANY\f[R] options and \f[I]MUST BE\f[R] presented +as the exact text of \[lq]none\[rq]. +.PP +The arguments to either the command line option or the environment +variable are in the form: +.PP +\f[C]:\f[R] +.PP +Specifying an empty string for either the \f[C]\f[R] or +\f[C]\f[R] results in the default being used for +that portion respectively. +.SS TCTI Defaults +.PP +When a TCTI is not specified, the default TCTI is searched for using +\f[I]dlopen(3)\f[R] semantics. +The tools will search for \f[I]tabrmd\f[R], \f[I]device\f[R] and +\f[I]mssim\f[R] TCTIs \f[B]IN THAT ORDER\f[R] and \f[B]USE THE FIRST ONE +FOUND\f[R]. +You can query what TCTI will be chosen as the default by using the +\f[B]\-v\f[R] option to print the version information. +The \[lq]default\-tcti\[rq] key\-value pair will indicate which of the +aforementioned TCTIs is the default. +.SS Custom TCTIs +.PP +Any TCTI that implements the dynamic TCTI interface can be loaded. +The tools internally use \f[I]dlopen(3)\f[R], and the raw +\f[I]tcti\-name\f[R] value is used for the lookup. +Thus, this could be a path to the shared library, or a library name as +understood by \f[I]dlopen(3)\f[R] semantics. +.SH TCTI OPTIONS +.PP +This collection of options are used to configure the various known TCTI +modules available: +.IP \[bu] 2 +\f[B]device\f[R]: For the device TCTI, the TPM character device file for +use by the device TCTI can be specified. +The default is \f[I]/dev/tpm0\f[R]. +.RS 2 +.PP +Example: \f[B]\-T device:/dev/tpm0\f[R] or \f[B]export +\f[BI]TPM2TOOLS_TCTI\f[B]=\[lq]device:/dev/tpm0\[rq]\f[R] +.RE +.IP \[bu] 2 +\f[B]mssim\f[R]: For the mssim TCTI, the domain name or IP address and +port number used by the simulator can be specified. +The default are 127.0.0.1 and 2321. +.RS 2 +.PP +Example: \f[B]\-T mssim:host=localhost,port=2321\f[R] or \f[B]export +\f[BI]TPM2TOOLS_TCTI\f[B]=\[lq]mssim:host=localhost,port=2321\[rq]\f[R] +.RE +.IP \[bu] 2 +\f[B]abrmd\f[R]: For the abrmd TCTI, the configuration string format is +a series of simple key value pairs separated by a `,' character. +Each key and value string are separated by a `=' character. +.RS 2 +.IP \[bu] 2 +TCTI abrmd supports two keys: +.RS 2 +.IP "1." 3 +`bus_name' : The name of the tabrmd service on the bus (a string). +.IP "2." 3 +`bus_type' : The type of the dbus instance (a string) limited to +`session' and `system'. +.RE +.PP +Specify the tabrmd tcti name and a config string of +\f[C]bus_name=com.example.FooBar\f[R]: +.IP +.nf +\f[C] +\[rs]\-\-tcti=tabrmd:bus_name=com.example.FooBar +\f[R] +.fi +.PP +Specify the default (abrmd) tcti and a config string of +\f[C]bus_type=session\f[R]: +.IP +.nf +\f[C] +\[rs]\-\-tcti:bus_type=session +\f[R] +.fi +.PP +\f[B]NOTE\f[R]: abrmd and tabrmd are synonymous. +the various known TCTI modules. +.RE +.SH EXAMPLES +.SS Setup +.PP +To load an object you first must create an object under a primary +object. +So the first step is to create the primary object. +.IP +.nf +\f[C] +tpm2_createprimary \-c primary.ctx +\f[R] +.fi +.PP +Step 2 is to create an object under the primary object. +.IP +.nf +\f[C] +tpm2_create \-C primary.ctx \-u key.pub \-r key.priv \-f pem \-o pub.pem +\f[R] +.fi +.PP +This creates the private and public portions of the TPM object. +With these object portions, it is now possible to load that object into +the TPM for subsequent use. +.SS Encoding an Object into a combined PEM format +.PP +The final step, is encoding the public and private portions of the +object into a PEM format. +.IP +.nf +\f[C] +tpm2_encodeobject \-C primary.ctx \-u key.pub \-r key.priv \-o priv.pem +\f[R] +.fi +.PP +The generated \f[C]priv.pem\f[R] can be used together with +\f[C]pub.pem\f[R] created in the step 2 of Setup section. +.SH Returns +.PP +Tools can return any of the following codes: +.IP \[bu] 2 +0 \- Success. +.IP \[bu] 2 +1 \- General non\-specific error. +.IP \[bu] 2 +2 \- Options handling error. +.IP \[bu] 2 +3 \- Authentication error. +.IP \[bu] 2 +4 \- TCTI related error. +.IP \[bu] 2 +5 \- Non supported scheme. +Applicable to tpm2_testparams. +.SH BUGS +.PP +Github Issues (https://github.com/tpm2-software/tpm2-tools/issues) +.SH HELP +.PP +See the Mailing +List (https://lists.linuxfoundation.org/mailman/listinfo/tpm2)