123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386 |
- .\" Automatically generated by Pandoc 1.19.2.4
- .\"
- .TH "tpm2_ecephemeral" "1" "" "tpm2\-tools" "General Commands Manual"
- .hy
- .SH NAME
- .PP
- \f[B]tpm2_ecephemeral\f[](1) \- Creates an ephemeral key for use in a
- two\-phase key exchange protocol.
- .SH SYNOPSIS
- .PP
- \f[B]tpm2_ecephemeral\f[] [\f[I]OPTIONS\f[]]
- .SH DESCRIPTION
- .PP
- \f[B]tpm2_ecephemeral\f[](1) \- Creates an ephemeral key for use in a
- two\-phase key exchange protocol.
- .SH OPTIONS
- .IP \[bu] 2
- \f[B]ARGUMENT\f[]=\f[I]ALGORITHM\f[]:
- .RS 2
- .PP
- Specify the ECC curve.
- Example ecc521.
- .RE
- .IP \[bu] 2
- \f[B]\-u\f[], \f[B]\-\-public\f[]=\f[I]FILE\f[]
- .RS 2
- .PP
- Specify the file path to save the ephemeral public point Q ≔ [r]G.
- .RE
- .IP \[bu] 2
- \f[B]\-t\f[], \f[B]\-\-counter\f[]=\f[I]FILE\f[]
- .RS 2
- .PP
- Specify file path to save the least\-significant 16 bits of commit
- count.
- .RE
- .SS References
- .SH Algorithm Specifiers
- .PP
- Options that take algorithms support "nice\-names".
- .PP
- There are two major algorithm specification string classes, simple and
- complex.
- Only certain algorithms will be accepted by the TPM, based on usage and
- conditions.
- .SS Simple specifiers
- .PP
- These are strings with no additional specification data.
- When creating objects, non\-specified portions of an object are assumed
- to defaults.
- You can find the list of known "Simple Specifiers Below".
- .SS Asymmetric
- .IP \[bu] 2
- rsa
- .IP \[bu] 2
- ecc
- .SS Symmetric
- .IP \[bu] 2
- aes
- .IP \[bu] 2
- camellia
- .SS Hashing Algorithms
- .IP \[bu] 2
- sha1
- .IP \[bu] 2
- sha256
- .IP \[bu] 2
- sha384
- .IP \[bu] 2
- sha512
- .IP \[bu] 2
- sm3_256
- .IP \[bu] 2
- sha3_256
- .IP \[bu] 2
- sha3_384
- .IP \[bu] 2
- sha3_512
- .SS Keyed Hash
- .IP \[bu] 2
- hmac
- .IP \[bu] 2
- xor
- .SS Signing Schemes
- .IP \[bu] 2
- rsassa
- .IP \[bu] 2
- rsapss
- .IP \[bu] 2
- ecdsa
- .IP \[bu] 2
- ecdaa
- .IP \[bu] 2
- ecschnorr
- .SS Asymmetric Encryption Schemes
- .IP \[bu] 2
- oaep
- .IP \[bu] 2
- rsaes
- .IP \[bu] 2
- ecdh
- .SS Modes
- .IP \[bu] 2
- ctr
- .IP \[bu] 2
- ofb
- .IP \[bu] 2
- cbc
- .IP \[bu] 2
- cfb
- .IP \[bu] 2
- ecb
- .SS Misc
- .IP \[bu] 2
- null
- .SS Complex Specifiers
- .PP
- Objects, when specified for creation by the TPM, have numerous
- algorithms to populate in the public data.
- Things like type, scheme and asymmetric details, key size, etc.
- Below is the general format for specifying this data:
- \f[C]<type>:<scheme>:<symmetric\-details>\f[]
- .SS Type Specifiers
- .PP
- This portion of the complex algorithm specifier is required.
- The remaining scheme and symmetric details will default based on the
- type specified and the type of the object being created.
- .IP \[bu] 2
- aes \- Default AES: aes128
- .IP \[bu] 2
- aes128\f[C]<mode>\f[] \- 128 bit AES with optional mode
- (\f[I]ctr\f[]|\f[I]ofb\f[]|\f[I]cbc\f[]|\f[I]cfb\f[]|\f[I]ecb\f[]).
- If mode is not specified, defaults to \f[I]null\f[].
- .IP \[bu] 2
- aes192\f[C]<mode>\f[] \- Same as aes128\f[C]<mode>\f[], except for a 192
- bit key size.
- .IP \[bu] 2
- aes256\f[C]<mode>\f[] \- Same as aes128\f[C]<mode>\f[], except for a 256
- bit key size.
- .IP \[bu] 2
- ecc \- Elliptical Curve, defaults to ecc256.
- .IP \[bu] 2
- ecc192 \- 192 bit ECC
- .IP \[bu] 2
- ecc224 \- 224 bit ECC
- .IP \[bu] 2
- ecc256 \- 256 bit ECC
- .IP \[bu] 2
- ecc384 \- 384 bit ECC
- .IP \[bu] 2
- ecc521 \- 521 bit ECC
- .IP \[bu] 2
- rsa \- Default RSA: rsa2048
- .IP \[bu] 2
- rsa1024 \- RSA with 1024 bit keysize.
- .IP \[bu] 2
- rsa2048 \- RSA with 2048 bit keysize.
- .IP \[bu] 2
- rsa4096 \- RSA with 4096 bit keysize.
- .SS Scheme Specifiers
- .PP
- Next, is an optional field, it can be skipped.
- .PP
- Schemes are usually \f[B]Signing Schemes\f[] or \f[B]Asymmetric
- Encryption Schemes\f[].
- Most signing schemes take a hash algorithm directly following the
- signing scheme.
- If the hash algorithm is missing, it defaults to \f[I]sha256\f[].
- Some take no arguments, and some take multiple arguments.
- .SS Hash Optional Scheme Specifiers
- .PP
- These scheme specifiers are followed by a dash and a valid hash
- algorithm, For example: \f[C]oaep\-sha256\f[].
- .IP \[bu] 2
- oaep
- .IP \[bu] 2
- ecdh
- .IP \[bu] 2
- rsassa
- .IP \[bu] 2
- rsapss
- .IP \[bu] 2
- ecdsa
- .IP \[bu] 2
- ecschnorr
- .SS Multiple Option Scheme Specifiers
- .PP
- This scheme specifier is followed by a count (max size UINT16) then
- followed by a dash(\-) and a valid hash algorithm.
- * ecdaa For example, ecdaa4\-sha256.
- If no count is specified, it defaults to 4.
- .SS No Option Scheme Specifiers
- .PP
- This scheme specifier takes NO arguments.
- * rsaes
- .SS Symmetric Details Specifiers
- .PP
- This field is optional, and defaults based on the \f[I]type\f[] of
- object being created and it\[aq]s attributes.
- Generally, any valid \f[B]Symmetric\f[] specifier from the \f[B]Type
- Specifiers\f[] list should work.
- If not specified, an asymmetric objects symmetric details defaults to
- \f[I]aes128cfb\f[].
- .SS Examples
- .SS Create an rsa2048 key with an rsaes asymmetric encryption scheme
- .PP
- \f[C]tpm2_create\ \-C\ parent.ctx\ \-G\ rsa2048:rsaes\ \-u\ key.pub\ \-r\ key.priv\f[]
- .SS Create an ecc256 key with an ecdaa signing scheme with a count of 4
- and sha384 hash
- .PP
- \f[C]/tpm2_create\ \-C\ parent.ctx\ \-G\ ecc256:ecdaa4\-sha384\ \-u\ key.pub\ \-r\ key.priv\f[]
- cryptographic algorithms \f[I]ALGORITHM\f[].
- .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[], \f[B]\-\-help=[man|no\-man]\f[]: 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 "man" option argument is specified,
- however if explicit "man" is requested, the tool will provide errors
- from man on stderr.
- If the "no\-man" 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[], See man(1) for more details.
- .RE
- .IP \[bu] 2
- \f[B]\-v\f[], \f[B]\-\-version\f[]: Display version information for this
- tool, supported tctis and exit.
- .IP \[bu] 2
- \f[B]\-V\f[], \f[B]\-\-verbose\f[]: 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[], \f[B]\-\-quiet\f[]: Silence normal tool output to stdout.
- .IP \[bu] 2
- \f[B]\-Z\f[], \f[B]\-\-enable\-errata\f[]: 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 "Transmission Interface" 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[] or \f[B]\-\-tcti\f[]
- .IP "2." 3
- The environment variable: \f[I]TPM2TOOLS_TCTI\f[].
- .PP
- \f[B]Note:\f[] 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[] options and \f[I]MUST BE\f[] presented as
- the exact text of "none".
- .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[]
- .PP
- Specifying an empty string for either the \f[C]<tcti\-name>\f[] or
- \f[C]<tcti\-option\-config>\f[] 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[] semantics.
- The tools will search for \f[I]tabrmd\f[], \f[I]device\f[] and
- \f[I]mssim\f[] TCTIs \f[B]IN THAT ORDER\f[] and \f[B]USE THE FIRST ONE
- FOUND\f[].
- You can query what TCTI will be chosen as the default by using the
- \f[B]\-v\f[] option to print the version information.
- The "default\-tcti" 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[], and the raw
- \f[I]tcti\-name\f[] 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[] 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[]: 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[].
- .RS 2
- .PP
- Example: \f[B]\-T device:/dev/tpm0\f[] or \f[B]export
- \f[I]TPM2TOOLS_TCTI\f[]="device:/dev/tpm0"\f[]
- .RE
- .IP \[bu] 2
- \f[B]mssim\f[]: 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[] or \f[B]export
- \f[I]TPM2TOOLS_TCTI\f[]="mssim:host=localhost,port=2321"\f[]
- .RE
- .IP \[bu] 2
- \f[B]abrmd\f[]: For the abrmd TCTI, the configuration string format is a
- series of simple key value pairs separated by a \[aq],\[aq] character.
- Each key and value string are separated by a \[aq]=\[aq] character.
- .RS 2
- .IP \[bu] 2
- TCTI abrmd supports two keys:
- .RS 2
- .IP "1." 3
- \[aq]bus_name\[aq] : The name of the tabrmd service on the bus (a
- string).
- .IP "2." 3
- \[aq]bus_type\[aq] : The type of the dbus instance (a string) limited to
- \[aq]session\[aq] and \[aq]system\[aq].
- .RE
- .PP
- Specify the tabrmd tcti name and a config string of
- \f[C]bus_name=com.example.FooBar\f[]:
- .PP
- \f[C]\\\-\-tcti=tabrmd:bus_name=com.example.FooBar\f[]
- .PP
- Specify the default (abrmd) tcti and a config string of
- \f[C]bus_type=session\f[]:
- .PP
- \f[C]\\\-\-tcti:bus_type=session\f[]
- .PP
- \f[B]NOTE\f[]: abrmd and tabrmd are synonymous.
- the various known TCTI modules.
- .RE
- .SH EXAMPLES
- .IP
- .nf
- \f[C]
- tpm2_ecephemeral\ \-u\ ecc.q\ \-t\ ecc.ctr\ ecc256
- \f[]
- .fi
- .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.01.org/mailman/listinfo/tpm2)
|