tpm2_hmac(1)

📦

version 5.8 · 10 versions

💖 NAME 💖

bestie. this is tpm2_hmac(1) from the General Commands Manual — the one and only, the main character of this page. it performs an HMAC operation with the TPM. that's it. that's the whole job. periodt. 💅

✨ SYNOPSIS ✨

tpm2_hmac [OPTIONS] [ARGUMENT]

🦋 DESCRIPTION 🦋

okay so tpm2_hmac(1) — it does an HMAC operation and hands you back the results. literally that simple. 🔥

if the argument file isn't specified, then the data gets read from stdin. so you can just pipe stuff in, no big deal, no cap.

the hashing algorithm defaults to the key's scheme, or sha256 if the key has a NULL scheme. slay.

output defaults to STDOUT and binary format unless you say otherwise via the -o and --hex options respectively. binary is the default vibe, so if you want readable hex you gotta ask for it. 🙈

🎀 OPTIONS 🎀

-c, --key-context=OBJECT — the context object of the symmetric signing key that's providing the HMAC key. it can be either a file or a handle number — whichever you're feeling. check the “Context Object Format” section below for deets. 🗝️
-p, --auth=AUTH — optional authorization value to use for the key that -c pointed at. yes, that key. 🔑
-g, --hash-algorithm=ALGORITHM — the hash algorithm you wanna use. algorithms follow the “formatting standards”, so go read the “Algorithm Specifiers” section. and if you want the actual list of what's supported, that's in “Supported Hash Algorithms”. ✨
--hex — converts the output hmac into hex format, and with no leading 0x. not me checking for that prefix like a fool. 😭
-o, --output=FILE — optional file to record the HMAC result in. defaults to STDOUT. 🫶
-t, --ticket=FILE — optional file to record the ticket result in. 🎫
--cphash=FILE — file path to record the hash of the command parameters. this is commonly called a cpHash. NOTE (read this bestie): when you select this option, the tool will not actually execute the command — it just returns a cpHash. so don't be out here expecting an HMAC, because you will not be getting one. 💀
ARGUMENT — the command line argument that specifies the file path for the data you want to HMAC. defaults to STDIN if you don't specify it. 🍓

📚 References 📚

this is where the page pulls out its little reference cards. buckle up. 🧚

🧸 Context Object Format 🧸

the type of a context object — whether it's a handle or a file name — gets figured out using this logic, in order:

if the argument is a file path, then the file is 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. (the page has a stray _OBJECT_ dangling off the end of that sentence — no idea, it's just art at this point 🫶)

🔐 Authorization Formatting 🔐

so authorization for using an object in TPM2.0 comes in 3 different forms:

Password
HMAC
Sessions

NOTE: “Authorizations default to the EMPTY PASSWORD when not specified”. so no auth value = empty password, iykyk. 🙈

for authentication with auth values, the tool commands implicitly generate an HMAC session. which means passwords are not transmitted unencrypted. iconic behaviour, honestly. 🎀

BUT — and this is the important part — that does not apply to passwords defined for objects. in that case, an HMAC session should be used (see tpm2_startauthsession(1)). don't skip that step, bestie.

🍓 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 don't have a prefix.

🌸 String

a string password, specified by the prefix str: — or its absence (raw string with no prefix at all) — is not interpreted, and gets used directly for authorization. straightforward. 💅

Examples

foobar
str:foobar

🌈 Hex-string

a hex-string password, specified by the prefix hex:, is converted from a hexidecimal form into a byte array form. the whole point? it lets you have passwords with non-printable and/or terminal un-friendly characters. obsessed. 🔥

Example

hex:1122334455667788

💜 File

a file based password, specified by the prefix file:, should be the path of a file containing the password to be read by the tool — or a - to use stdin. 🫶

why bother? because storing passwords in files prevents information leakage — passwords passed as options can be read from the process list or from common shell history features. so like, do it properly. 😭

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 with the session handle (eg policy password), then append a + and a string, as described up 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 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 looks like this:

<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

(yep, that's a heading with nothing under it in the original. we respect the empty vibe. 🫶)

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

specifying AUTH. 👑

🔐 Authorization Formatting 🔐 (yes, again — the page literally prints it twice, iykyk)

okay so not me noticing the original just... repeats this whole block. but we keep every detail in this house, so here's the tea again, bestie. same rules, no changes, no cap. 💀

authorization for use of an object in TPM2.0 comes in 3 different forms:

Password
HMAC
Sessions

NOTE: “Authorizations default to the EMPTY PASSWORD when not specified”.

for authentication with auth values, the tool commands implicitly generate an HMAC session, so passwords are not transmitted unencrypted. this does not apply to passwords defined for objects — in that case, an HMAC session should be used (see tpm2_startauthsession(1)). 🦋

🍓 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 don't have a prefix.

🌸 String

a string password, specified by the prefix str: — or its absence (a raw string with no prefix) — is not interpreted, and is directly used for authorization.

Examples

foobar
str:foobar

🌈 Hex-string

a hex-string password, specified by the prefix hex:, gets converted from a hexidecimal form into a byte array form, which allows passwords with non-printable and/or terminal un-friendly characters. 🌟

Example

hex:1122334455667788

💜 File

a file based password, specified by the 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, because 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). 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 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 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 as follows:

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

the PCR spec is documented in in the section “PCR bank specifiers”. (yes, "in in". the page said it, not me. 🙈)

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

(empty again. consistency queen. 💅)

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

specifying AUTH.

ALGORITHM.

🌟 COMMON OPTIONS 🌟

this collection of options is common to many programs and provides info that many users may expect. so like, the shared group-chat of options. 🫶

-h, --help=[man|no-man] — displays the tool's manpage. by default it attempts to invoke the manpager for the tool, but on failure it'll output a short tool summary instead. same behaviour if you pass the man option argument — except if you explicitly request man, the tool will provide errors from man on stderr. if you specify the no-man option, or the manpager just fails, the short options get output to stdout. to actually use the manpages feature you need the manpages 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. 🔍
-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. and 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, then the transient parent object will be flushed too. autoflush can also be activated if the environment variable TPM2TOOLS_AUTOFLUSH is set to yes or true. 🚿 (the page adds a stray "information many users may expect." right at the end there — we love a dangling sentence, it's giving editorial chaos 💀)

🌈 TCTI Configuration 🌈

Okay bestie, so the TCTI — that's "Transmission Interface" if you're fancy — is literally just the communication mechanism with the TPM. Like the group chat between you and your TPM. And here's the slay part: you can swap TCTIs out to talk to TPMs across totally different mediums. Versatile icon ✨

To control the TCTI, the tools respect these, in order:

the command line option -T or --tcti
the environment variable: TPM2TOOLS_TCTI

Heads up: the command line option always overrides the environment variable. Always always. No cap. 💅

The current known TCTIs are:

tabrmd — the resource manager, called tabrmd. Note that tabrmd and abrmd as a tcti name are synonymous. Same vibe, two names 🫶
mssim — typically used for communicating to the TPM software simulator.
device — used when talking directly to a TPM device file.
none — do not initialize 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 you try to use them without a TCTI connection. This one does not support ANY options and MUST BE presented as the exact text of none — like, literally that exact string, don't get cute with 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 <tcti-option-config> results in the default being used for that portion respectively. Empty = default, it's giving "no thoughts, head empty, works fine" 🎀

🌸 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. Bestie, the order matters, this is not a drill 🔥

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. Iconic little peek behind the curtain 👑

🦋 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 it could be a path to the shared library, or a library name as understood by dlopen(3) semantics. Build your own, plug it in, main character energy 💜

✨ TCTI OPTIONS ✨

This collection of options are 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.
- 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 💖

🎀 Setup 🎀

# create a primary object
tpm2_createprimary -c primary.ctx

# create an hmac key
tpm2_create -C primary.ctx -G hmac -c hmac.key

⭐ Perform an HMAC with Default Hash Algorithm ⭐

Perform an hmac using the key's default scheme (hash algorithm) and output to stdout in hexidecimal format.

tpm2_hmac -c hmac.key --hex data.in
e6eda48a53a9ddbb92f788f6d98e0372d63a408afb11aca43f522a2475a32805

Look at that hex output. Ate. Left no crumbs. 🔥

🫶 Returns 🫶

Tools can return any of the following codes:

0 — Success. We love to see it 💖
1 — General non-specific error.
2 — Options handling error.
3 — Authentication error.
4 — TCTI related error.
5 — Non supported scheme. Applicable to tpm2_testparams.

💀 BUGS 💀

Github Issues. (Yes that's literally it, go open one, bestie, we're listening 🙈)

🌸 HELP 🌸

See the Mailing List.

👑 License 👑

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

And that's the whole page, bestie! 🧚 Source and version: tpm2-tools, page tpm2_hmac(1). Manifesting a flawless HMAC for you and your TPM, mwah 💅🍓

📦 where this page comes from

arch rolling: tpm2-tools 5.8-1 · BSD-3-Clause
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms