tpm2-tools/SOURCES/add_pregenerated_doc.patch

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]<pcr\-spec>=<raw\-pcr\-file>\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]<tcti\-name>:<tcti\-option\-config>\f[R]
+.PP
+Specifying an empty string for either the \f[C]<tcti\-name>\f[R] or
+\f[C]<tcti\-option\-config>\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)