tpm2_hash(1)

📦
version 5.8 · 10 versions
, in arch rolling

🌸 tpm2_hash(1) — the General Commands Manual glow-up 🌸

okay bestie so this one is tpm2_hash(1), from the General Commands Manual, and she is literally the TPM's personal hash girlie. buckle up 💅

✨ NAME ✨

tpm2_hash(1) — does a hash operation with the TPM. that's it, that's the whole vibe. no cap. 🫶

✨ SYNOPSIS ✨

tpm2_hash [OPTIONS] [ARGUMENT OR STDIN]

✨ DESCRIPTION ✨

so tpm2_hash(1) does a hash operation on a file and gives you the results back. if you don't give it an argument, then it just reads the data from stdin — very "i'll take whatever you feed me" of her. 🍓

here's the part that actually matters: if the results of the hash are gonna be used in a signing operation that uses a restricted signing key, then the ticket this command hands back can indicate that the hash is safe to sign. that's the whole ticket thing. iykyk 🔥

output defaults to stdout in binary format, unless you say otherwise via -o and –hex respectively. she's giving raw-bytes main character energy until you ask for hex.

✨ OPTIONS ✨

  • -C, --hierarchy=OBJECT — which hierarchy to use for the ticket. no value specified? she defaults to o, a.k.a. TPM_RH_OWNER. the supported options are:
    • o for TPM_RH_OWNER
    • p for TPM_RH_PLATFORM
    • e for TPM_RH_ENDORSEMENT
    • n for TPM_RH_NULL
  • -g, --hash-algorithm=ALGORITHM — the hashing algorithm for the digest operation. pick your girl. 🎀
  • --hex — converts the output hmac to hex format, and there is no leading 0x, ok? none. zero. she said no prefix. 💅
  • -o, --output=FILE or STDOUT — optional file to save the hash result to. defaults to stdout in hex form.
  • -t, --ticket=TICKET_FILE — optional file record of the ticket result. also defaults to stdout in hex form.
  • ARGUMENT or STDIN — if you pass a command line argument, that argument specifies the FILE to hash. if you don't, see above, stdin gets the job.

📎 References

🦋 Context Object Format

the type of a context object — whether it's a handle or a file name — is decided by this logic, and the order matters, so pay attention babes:

  • if the argument is a file path, then the file gets loaded as a restored TPM transient object.
  • if the argument is a prefix match on one of these:
    • owner: — the owner hierarchy
    • platform: — the platform hierarchy
    • endorsement: — the endorsement hierarchy
    • lockout: — the lockout control persistent object
  • if the argument can be loaded as a number, it gets treated as a handle, like 0x81010013, and used directly._OBJECT_.

(yes, that _OBJECT_ is just sitting there. she's quirky like that. we love her anyway 🌈)

🔐 Authorization Formatting

authorization for using an object in TPM2.0 can come in three different forms:

  1. Password
  2. HMAC
  3. Sessions
NOTE: "Authorizations default to the EMPTY PASSWORD when not specified". that's a quote, not a drill. ⭐

for authentication with auth values, the tool commands implicitly generate an HMAC session — so passwords are not transmitted unencrypted. the way that works is so real of them. 🧚

BUT — and this is a big but — this does not apply to passwords defined for objects. in that case, an HMAC session should be used (see tpm2_startauthsession(1)). noted. logged. remembered. 🎀

🔑 Passwords

passwords get interpreted in the forms below, using prefix identifiers.

Note: by default, passwords are assumed to be in the string form when they don't have a prefix.

🌸 String

a string password, specified by the prefix str: — or, honestly, by the absence of a prefix (raw string, no prefix) — is not interpreted at all, and is directly used for authorization. she's not reading into it. she's taking you at face value. 🙈

Examples

foobar
str:foobar

🌸 Hex-string

a hex-string password is specified by the prefix hex:, and gets converted from a hexidecimal form into a byte array form. that means you can have passwords with non-printable and/or terminal un-friendly characters. living dangerously, slay. 💀

Example

hex:1122334455667788

🌸 File

a file-based password is specified with the prefix file: and 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, because passwords passed as options can be read from the process list or from common shell history features. protect yourself bestie 🫶

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 you're using a policy session to authorize the use of an object, prefix the option argument with the session keyword. then point at a path to a session file that was created with tpm2_startauthsession(1).

optionally — if the session requires an auth value to be sent along with the session handle (eg policy password) — then append a + and a string as described in the Passwords section above. that's the little combo move. ✨

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 authvalue 0x11223344:

session:session.ctx+hex:11223344

🌸 PCR Authorizations

you can satisfy a PCR policy using the pcr: prefix and the PCR minilanguage. the PCR minilanguage is literally:

<pcr-spec>=<raw-pcr-file>

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

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

PCR bank specifiers

(that's the section. it's right there. she's a little mysterious. 👑)

Examples

to satisfy a PCR policy of sha256 on banks 0, 1, 2 and 3, use a specifier of:

pcr:sha256:0,1,2,3

ALGORITHM.

✨ COMMON OPTIONS ✨

this collection of options is common to many programs and provides information that many users may expect. the group chat classics, fr fr.

  • -h, --help=[man|no-man] — displays the tool's manpage. by default it tries to invoke the manpager for the tool, but on failure it'll output a short tool summary. that's the same behavior you get if you specify the man option argument — however, if man is explicitly requested, the tool will provide errors from man on stderr. if the no-man option is specified, or the manpager fails, the short options get output to stdout.

to successfully use the manpages feature, the manpages need to be installed or on MANPATH. see man(1) for more details. 💜

  • -v, --version — displays version information for this tool, the supported tctis, and exits.
  • -V, --verbose — increases the information the tool prints to the console during its execution. when you use this option, the file and line number get printed. she's being transparent with you 🦋
  • -Q, --quiet — silences normal tool output to stdout. shhh.
  • -Z, --enable-errata — enables the application of errata fixups. useful if an errata fixup needs to be applied to commands sent to the TPM. defining the environment variable TPM2TOOLS_ENABLE_ERRATA is equivalent.
  • -z, --pwd-session — uses a password session instead of an HMAC session for authentication. a clear text password is passed to the TPM to authorize the action. this option can be used to avoid problems when unsalted sessions are used in OpenSSL FIPS mode. if auth values are used, a salted session should be used for authentication. 🔥
  • -R, --autoflush — enables autoflush for transient objects created by the command. if a parent object is loaded from a context file, also the transient parent object will be flushed. autoflush can also be activated if the environment variable TPM2TOOLS_AUTOFLUSH is is set to yes or true. (yes, the double "is is" is canon. we keep her exactly as she is 🎀) information 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. she's flexible like that 💅

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 variable. always. no exceptions. periodt.

the current known TCTIs are:

  • tabrmd — the resource manager, called tabrmd. note that tabrmd and abrmd as a tcti name are synonymous.
  • mssim — typically used for communicating to the TPM software simulator.
  • device — used when talking directly to a TPM device file.
  • 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 don't 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". she means it. 💀

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 the <tcti-option-config> results in the default being used for that portion respectively. easy. 🌈

🧚 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. like, that's the priority list, respect it. 👑

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 indicate which of the aforementioned TCTIs is the default. iykyk 💖

🧚 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. so this could be a path to the shared library, or a library name as understood by dlopen(3) semantics. go off, custom library 🦋

✨ TCTI OPTIONS ✨

this collection of options is used to configure the various known TCTI modules available:

  • 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="device:/dev/tpm0"

  • mssim — for the mssim TCTI, the domain name or IP address and port number used by the simulator can be specified. the defaults are 127.0.0.1 and 2321.

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

  • abrmd — 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. very "just give me the pairs" of her 🍓
    • the 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.example.FooBar:

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

specify the default (abrmd) tcti and a config string of bus_type=session:

--tcti:bus_type=session
NOTE: abrmd and tabrmd are synonymous. the various known TCTI modules.

✨ EXAMPLES ✨

🌟 Hash a file with sha1 hash algorithm and save the hash and ticket to a file

tpm2_hash -C e -g sha1 -o hash.bin -t ticket.bin data.txt

that's the whole move. -C e for the endorsement hierarchy, -g sha1 for the algorithm, -o hash.bin for the hash, -t ticket.bin for the ticket, and data.txt as the file to hash. iconic, honestly. 🎀

💖 RETURNS 💖

okay so bestie, when the tool finishes doing its thing, it's gonna hand back one of these codes — think of it like the vibe check at the end of the run:

  • 0 — Success. slay, it worked, we love to see it ✨
  • 1 — General non-specific error. the vaguest possible L 😭 no further info, it just... didn't go
  • 2 — Options handling error. you fumbled the flags, bestie — check your args
  • 3 — Authentication error. the auth didn't pass the vibe check 🫶
  • 4 — TCTI related error. something went sideways in the TCTI layer, iykyk
  • 5 — Non supported scheme. this one's only applicable to tpm2_testparams, so like... not your problem here

🦋 BUGS 🦋

Found a bug? no cap, go file it on Github Issues. the devs wanna hear it fr fr 💅

🌸 HELP 🌸

Need a hand? See the Mailing List — that's where the community lives 👑

🎀 License 🎀

This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). iconic, honestly.

and that's the whole page, bestie!! 💜 this lil beauty comes from tpm2-tools and lives under the name tpm2_hash(1) — go forth and hash responsibly ✨🫶🎀

📦 where this page comes from