Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
tpm2_loadexternal(1)	    General Commands Manual	  tpm2_loadexternal(1)

NAME
       tpm2_loadexternal(1) - Load an external object into the TPM.

SYNOPSIS
       tpm2_loadexternal [OPTIONS]

DESCRIPTION
       tpm2_loadexternal(1)  -	This command loads an external object into the
       TPM, forgoing TPM protections.  Ie, the key material is	not  protected
       by  the	parent	object's seed.	The command allows loading of just the
       public portion of an object or both the public and private portions  of
       an object.

       The  tool  outputs  the	name of	the loaded object in a YAML dictionary
       format with the key name	where the value	for that key is	 the  name  of
       the object in hex format, for example:

	      name: 000bac25cb8743111c8e1f52f2ee7279d05d3902a18dd1af694db5d1afa7adf1c8b3

       It also saves a context file for	future interactions with the object.

OPTIONS
       o -C, --hierarchy=OBJECT:
	 Hierarchy  to	use  for  the  ticket, optional.  Defaults to n, null.
	 Supported options are:

	 o o for the owner hierarchy.

	 o p for the platform hierarchy.

	 o e for the endorsement hierarchy.

	 o n for the null hierarchy.

       o -G, --key-algorithm=ALGORITHM:
	 The algorithm used by the key to be imported.	Supports:

	 o aes - AES 128,192 or	256 key.

	 o rsa - RSA 1024 or 2048 key.

	 o ecc - ECC NIST P192,	P224, P256, P384 or P521  public  and  private
	   key.

       o -u, --public=FILE:
	 The  public  portion  of the object, this can be one of the following
	 file formats:

	 o TSS - The TSS/TPM format.  For example from option  -u  of  command
	   tpm2_create(1).

	 o RSA	-  OSSL	 PEM formats.  For example public.pem from the command
	   openssl rsa -in private.pem -out public.pem -pubout

	 o ECC - OSSL PEM formats.  For	example	public.pem  from  the  command
	   openssl ec -in private.ecc.pem -out public.ecc.pem -pubout

       o -r, --private=FILE:
	 The  sensitive	portion	of the object, optional.  If one wishes	to use
	 the private portion of	a key, this must be  specified.	  Like	option
	 -u, this command takes	files in the following format:

	 o RSA	-  OSSL	PEM formats.  For example private.pem from the command
	   openssl genrsa -out private.pem 2048	Since an RSA public key	can be
	   derived  from  the private PEM file,	their is no need to specify -u
	   for the public portion.

	 Note: The private portion does	not respect TSS	formats	as it's	impos-
	 sible to get a	TPM2B_SENSITIVE	output from a previous command.

       o -p, --auth=AUTH:

	 The authorization value for the key, optional.

       o -L, --policy=POLICY_FILE:

	 The  input  policy  file,  optional.  A file containing the hash of a
	 policy	derived	from tpm2_createpolicy.

       o -g, --hash-algorithm=ALGORITHM:

	 The hash algorithm for	generating the objects name.  This is optional
	 and  defaults	to  sha256 when	not specified.	However, load external
	 supports having a null	name algorithm.	 In this case, no cryptograph-
	 ic  binding  checks  between the public and private portions are per-
	 formed.

       o -a, --attributes=ATTRIBUTES:

	 The object attributes,	optional.  The default for created objects is:
	 TPMA_OBJECT_SIGN_ENCRYPT|TPMA_OBJECT_DECRYPT.	 Optionally,  if -p is
	 specified or no -p or -L is specified	then  TPMA_OBJECT_USERWITHAUTH
	 is added to the default attribute set.

	 Note:	If  specifying	attributes,  the  TPM  will reject certain at-
	 tributes like TPMA_OBJECT_FIXEDTPM, as	 those	guarantees  cannot  be
	 made.

       o -c, --key-context=FILE

	 The file name to save the object context, required.

       o -n, --name=FILE:

	 An  optional  file to save the	object name, which is in a binary hash
	 format.  The size of the hash is based	on name	algorithm  or  the  -g
	 option.

       o --passin=OSSL_PEM_FILE_PASSWORD

	 An  optional password for an Open SSL (OSSL) provided input file.  It
	 mirrors the -passin option of OSSL and	is known to support the	 pass,
	 file,	env,  fd  and  plain password formats of openssl.  (see	man(1)
	 openssl) for more.

   References
Context	Object Format
       The type	of a context object, whether it	is a handle or file  name,  is
       determined according to the following logic in-order:

       o If the	argument is a file path, then the file is loaded as a restored
	 TPM transient object.

       o If the	argument is a prefix match on one of:

	 o owner: the owner hierarchy

	 o platform: the platform hierarchy

	 o endorsement:	the endorsement	hierarchy

	 o lockout: the	lockout	control	persistent object

       o If the	argument argument can be loaded	as a number it will  be	 treat
	 as a handle, e.g.  0x81010013 and used	directly.OBJECT.

Authorization Formatting
       Authorization  for  use	of an object in	TPM2.0 can come	in 3 different
       forms: 1.  Password 2.  HMAC 3.	Sessions

       NOTE: "Authorizations default to	the EMPTY  PASSWORD  when  not	speci-
       fied".

   Passwords
       Passwords  are  interpreted  in	the following forms below using	prefix
       identifiers.

       Note: By	default	passwords are assumed to be in the  string  form  when
       they do not have	a prefix.

   String
       A  string  password,  specified	by  prefix "str:" or it's absence (raw
       string without prefix) is not interpreted, and is directly used for au-
       thorization.

   Examples
	      foobar
	      str:foobar

   Hex-string
       A  hex-string  password,	specified by prefix "hex:" is converted	from a
       hexidecimal form	into a byte array form,	thus allowing  passwords  with
       non-printable and/or terminal un-friendly characters.

   Example
	      hex:0x1122334455667788

   File
       A  file	based password,	specified be prefix "file:" should be the path
       of a file containing the	password to be read by the tool	or  a  "-"  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.

   Examples
	      #	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

   Sessions
       When  using  a policy session to	authorize the use of an	object,	prefix
       the option argument with	the session keyword.  Then indicate a path  to
       a session file that was created with tpm2_startauthsession(1).  Option-
       ally, 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 Passwords	section.

   Examples
       To use a	session	context	file called session.ctx.

	      session:session.ctx

       To use a	session	context	file called session.ctx	AND send the authvalue
       mypassword.

	      session:session.ctx+mypassword

       To use a	session	context	file called session.ctx	AND send the HEX auth-
       value 0x11223344.

	      session:session.ctx+hex:11223344

   PCR Authorizations
       You can satisfy a PCR policy using the "pcr:" prefix and	the PCR	 mini-
       language.       The     PCR     minilanguage	is     as     follows:
       <pcr-spec>=<raw-pcr-file>

       The PCR spec is documented in in	the section "PCR bank specifiers".

       The raw-pcr-file	is an optional the output of the raw PCR  contents  as
       returned	by tpm2_pcrread(1).

       PCR bank	specifiers (common/pcr.md)

   Examples
       To satisfy a PCR	policy of sha256 on banks 0, 1,	2 and 3	use a specifi-
       er of:

	      pcr:sha256:0,1,2,3

       specifying AUTH.

Algorithm Specifiers
       Options that take algorithms support "nice-names".

       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.

   Simple specifiers
       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".

   Asymmetric
       o rsa

       o ecc

   Symmetric
       o aes

       o camellia

   Hashing Algorithms
       o sha1

       o sha256

       o sha384

       o sha512

       o sm3_256

       o sha3_256

       o sha3_384

       o sha3_512

   Keyed Hash
       o hmac

       o xor

   Signing Schemes
       o rsassa

       o rsapss

       o ecdsa

       o ecdaa

       o ecschnorr

   Asymmetric Encryption Schemes
       o oaep

       o rsaes

       o ecdh

   Modes
       o ctr

       o ofb

       o cbc

       o cfb

       o ecb

   Misc
       o null

   Complex Specifiers
       Objects,	when specified for creation by the TPM,	 have  numerous	 algo-
       rithms  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: <type>:<scheme>:<symmetric-details>

   Type	Specifiers
       This  portion  of the complex algorithm specifier is required.  The re-
       maining scheme and symmetric details will default  based	 on  the  type
       specified and the type of the object being created.

       o aes - Default AES: aes128

       o aes128<mode>  - 128 bit AES with optional mode	(ctr|ofb|cbc|cfb|ecb).
	 If mode is not	specified, defaults to null.

       o aes192<mode> -	Same as	aes128<mode>, except for a 192 bit key size.

       o aes256<mode> -	Same as	aes128<mode>, except for a 256 bit key size.

       o ecc - Elliptical Curve, defaults to ecc256.

       o ecc192	- 192 bit ECC

       o ecc224	- 224 bit ECC

       o ecc256	- 256 bit ECC

       o ecc384	- 384 bit ECC

       o ecc521	- 521 bit ECC

       o rsa - Default RSA: rsa2048

       o rsa1024 - RSA with 1024 bit keysize.

       o rsa2048 - RSA with 2048 bit keysize.

       o rsa4096 - RSA with 4096 bit keysize.

   Scheme Specifiers
       Next, is	an optional field, it can be skipped.

       Schemes are usually Signing Schemes or Asymmetric  Encryption  Schemes.
       Most signing schemes take a hash	algorithm directly following the sign-
       ing scheme.  If the hash	algorithm is missing, it defaults  to  sha256.
       Some take no arguments, and some	take multiple arguments.

   Hash	Optional Scheme	Specifiers
       These  scheme  specifiers are followed by a dash	and a valid hash algo-
       rithm, For example: oaep-sha256.

       o oaep

       o ecdh

       o rsassa

       o rsapss

       o ecdsa

       o ecschnorr

   Multiple Option Scheme Specifiers
       This scheme specifier is	followed by a count  (max  size	 UINT16)  then
       folloed	by a dash(-) and a valid hash algorithm.  * ecdaa For example,
       ecdaa4-sha256.  If no count is specified, it defaults to	4.

   No Option Scheme Specifiers
       This scheme specifier takes NO arguments.  * rsaes

   Symmetric Details Specifiers
       This field is optional, and defaults based on the type of object	 being
       created	and it's attributes.  Generally, any valid Symmetric specifier
       from the	Type Specifiers	list should work.  If not specified, an	 asym-
       metric objects symmetric	details	defaults to aes128cfb.

   Examples
   Create an rsa2048 key with an rsaes asymmetric encryption scheme
       tpm2_create -C parent.ctx -G rsa2048:rsaes -u key.pub -r	key.priv

   Create an ecc256 key	with an	ecdaa signing scheme with a count of 4
       and sha384 hash

       /tpm2_create -C parent.ctx -G ecc256:ec-
       daa4-sha384 -u key.pub -r key.priv cryptographic	algorithms ALGORITHM.

Object Attributes
       Object Attributes are used to control various properties	of created ob-
       jects.	When  specified	 as an option, either the raw bitfield mask or
       "nice-names" may	be used.  The values can be found in Table 31  Part  2
       of the TPM2.0 specification, which can be found here:

       <https://trustedcomputinggroup.org/wp-content/uploads/TPM-
       Rev-2.0-Part-2-Structures-01.38.pdf>

       Nice names are calculated by taking the name field of table 31 and  re-
       moving  the  prefix TPMA_OBJECT_	and lowercasing	the result.  Thus, TP-
       MA_OBJECT_FIXEDTPM becomes fixedtpm.  Nice names	can  be	 joined	 using
       the bitwise or "|" symbol.

       For instance, to	set The	fields TPMA_OBJECT_FIXEDTPM, TPMA_OBJECT_NODA,
       and TPMA_OBJECT_SIGN_ENCRYPT, the argument would	be:

       fixedtpm|noda|sign specifying the object	attributes ATTRIBUTES.

COMMON OPTIONS
       This collection of options are common to	many programs and provide  in-
       formation that many users may expect.

       o -h,  --help=[man|no-man]:  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  re-
	 quested,  the	tool  will  provide errors from	man on stderr.	If the
	 "no-man" option if specified, or the manpager fails,  the  short  op-
	 tions will be output to stdout.

	 To  successfully use the manpages feature requires the	manpages to be
	 installed or on MANPATH, See man(1) for more details.

       o -v, --version:	Display	version	information for	this  tool,  supported
	 tctis and exit.

       o -V,  --verbose:  Increase the information that	the tool prints	to the
	 console during	its execution.	When using this	option	the  file  and
	 line number are printed.

       o -Q, --quiet: Silence normal tool output to stdout.

       o -Z, --enable-errata: 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.  in-
	 formation many	users may expect.

TCTI Configuration
       The TCTI	or "Transmission Interface"  is	 the  communication  mechanism
       with  the TPM.  TCTIs can be changed for	communication with TPMs	across
       different mediums.

       To control the TCTI, the	tools respect:

       1. The command line option -T or	--tcti

       2. The environment variable: TPM2TOOLS_TCTI.

       Note: The command line option always overrides  the  environment	 vari-
       able.

       The current known TCTIs are:

       o tabrmd	     -	   The	   resource	manager,     called	tabrmd
	 (https://github.com/tpm2-software/tpm2-abrmd).	 Note that tabrmd  and
	 abrmd as a tcti name are synonymous.

       o mssim	- Typically used for communicating to the TPM software simula-
	 tor.

       o device	- Used when talking directly to	a TPM device file.

       o 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 ANY options and MUST BE presented as
	 the exact text	of "none".

       The arguments to	either the command  line  option  or  the  environment
       variable	are in the form:

       <tcti-name>:<tcti-option-config>

       Specifying  an  empty  string  for  either the <tcti-name> or <tcti-op-
       tion-config> results in the default being used for that portion respec-
       tively.

   TCTI	Defaults
       When  a	TCTI  is not specified,	the default TCTI is searched for using
       dlopen(3) semantics.  The tools will  search  for  tabrmd,  device  and
       mssim  TCTIs  IN	THAT ORDER and USE THE FIRST ONE FOUND.	 You can query
       what TCTI will be chosen	as the default by using	the -v option to print
       the  version information.  The "default-tcti" key-value pair will indi-
       cate which of the aforementioned	TCTIs is the default.

   Custom TCTIs
       Any TCTI	that implements	the dynamic TCTI interface can be loaded.  The
       tools internally	use dlopen(3), and the raw tcti-name value is used for
       the lookup.  Thus, this could be	a path to the shared library, or a li-
       brary name as understood	by dlopen(3) semantics.

TCTI OPTIONS
       This collection of options are used to configure	the various known TCTI
       modules available:

       o device: For the device	TCTI, the TPM character	device file for	use by
	 the device TCTI can be	specified.  The	default	is /dev/tpm0.

	 Example:    -T	  device:/dev/tpm0   or	  export   TPM2TOOLS_TCTI="de-
	 vice:/dev/tpm0"

       _o mssim:	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.

	 Example: -T mssim:host=localhost,port=2321  or	 export	 TPM2TOOLS_TC-
	 TI="mssim:host=localhost,port=2321"

       _o abrmd:	 For  the abrmd	TCTI, the configuration	string format is a se-
	 ries of simple	key value pairs	separated by a	','  character.	  Each
	 key and value string are separated by a '=' character.

	 o TCTI	abrmd supports two keys:

	   1. 'bus_name'  :  The  name	of  the	 tabrmd	 service on the	bus (a
	      string).

	   2. 'bus_type' : The type of the dbus	instance (a string) limited to
	      'session'	and 'system'.

	 Specify  the tabrmd tcti name and a config string of bus_name=com.ex-
	 ample.FooBar:

	 \--tcti=tabrmd:bus_name=com.example.FooBar

	 Specify the default (abrmd) tcti and a	config string of bus_type=ses-
	 sion:

	 \--tcti:bus_type=session

	 NOTE:	abrmd  and tabrmd are synonymous.  the various known TCTI mod-
	 ules.

NOTES
       o If the	hierarchy is null or the name hashing algorithm	is null, tick-
	 ets produced using the	object will be NULL.

       o If  the private portion of an object is specified, the	hierarchy must
	 be null or the	TPM will reject	loading	it.

EXAMPLES
   Load	a TPM generated	public key into	the owner hierarchy
	      tpm2_createprimary -c primary.ctx

	      tpm2_create -C primary.ctx -u pub.dat -r priv.dat

	      tpm2_loadexternal	-C o -u	pub.dat	-c pub.ctx
	      name: 000b9be4d7c6193a57e1bfc86a42a6b03856a91d2f9e77c6cbdb796a783d52d4b3b9

   Load	an RSA public key into the owner hierarchy
	      openssl genrsa -out private.pem 2048

	      openssl rsa -in private.pem -out public.pem -outform PEM -pubout

	      tpm2_loadexternal	-C o -Grsa -u public.pem -c key.ctx
	      name: 000b7b91d304d16995d42792b57d0fb25df7abe5fdd8afe9950730e00dc5b934ddbc

   Load	an RSA key-pair	into the null hierarchy
	      openssl genrsa -out private.pem 2048

	      tpm2_loadexternal	-C n -Grsa -r private.pem -c key.ctx
	      name: 000b635ea220b6c62ec1d02343859dd203c8ac5dad82ebc5b124e407d2502f88691f

   Load	an AES key into	the null hierarchy
	      dd if=/dev/urandom of=sym.key bs=1 count=16

	      tpm2_loadexternal	-C n -Gaes -r sym.key -c key.ctx
	      name: 000bfc4d8dd7e4f921bcc9dca4b04f49564243cd9def129a3740002bfd4b9e966d34

Returns
       Tools can return	any of the following codes:

       o 0 - Success.

       o 1 - General non-specific error.

       o 2 - Options handling error.

       o 3 - Authentication error.

       o 4 - TCTI related error.

       o 5 - Non supported scheme.  Applicable to tpm2_testparams.

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

HELP
       See the Mailing List (https://lists.01.org/mailman/listinfo/tpm2)

tpm2-tools						  tpm2_loadexternal(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | Context Object Format | Authorization Formatting | Algorithm Specifiers | Object Attributes | COMMON OPTIONS | TCTI Configuration | TCTI OPTIONS | NOTES | EXAMPLES | Returns | BUGS | HELP

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tpm2_loadexternal&sektion=1&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help