tpm2_pcrallocate(1)

📦
version 5.8 · 10 versions
, in arch rolling

💖 tpm2_pcrallocate(1) 💖

okay so this is a General Commands Manual page for tpm2_pcrallocate(1) and honestly? it's giving main character energy for your TPM config. let's get into it bestie ✨

🌸 NAME 🌸

tpm2_pcrallocate(1) — configure PCRs and bank algorithms. that's literally it, that's the whole vibe 🎀

🦋 SYNOPSIS 🦋

tpm2_pcrallocate [OPTIONS] [*ARGUMENT]

💜 DESCRIPTION 💜

okay so tpm2_pcrallocate(1) is the tool that lets you (yes you, bestie) specify a PCR allocation for the TPM. an allocation is just the enabling or disabling of PCRs and their banks — no cap. a PCR can have multiple banks, and each bank is tied to a specific hashing algorithm. you tell it what you want through the argument, iykyk.

if you give it no allocation at all, it'll default to SHA1 and SHA256 banks with PCRs 0 - 23 allocated. defaults are cute like that 💅

so the allocation is basically a list of banks plus the pcrs you picked. the values should follow the PCR bank specifiers standards — check that section below, it's iconic 🌟

heads up: the new allocations don't kick in until the next reboot. so like, don't panic when nothing changes immediately 😭
also note: this command requires platform authorization. periodt. 🔑

✨ OPTIONS ✨

  • -P, --auth=AUTH — optional authorization value. these should follow the authorization formatting standards — see the Authorization Formatting section below 🫶
  • ARGUMENT — the command line argument that specifies the PCR allocation. this is where you tell it what you want, bestie.
  • --cphash=FILE — file path to record the hash of the command parameters. this is commonly called cpHash.
NOTE: when you pick this option, the tool won't actually execute the command — it just returns a cpHash. like it's just here for the vibes 💀

🔥 References 🔥

🧚 Context Object Format 🧚

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

  • 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:
    • 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'll be treated 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 specified". so like, no auth = empty password, that's the default bestie 🙈

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

🔑 Passwords 🔑

passwords get 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. easy peasy 💖

🍓 String 🍓

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

Examples

foobar
str:foobar

🌈 Hex-string 🌈

a hex-string password, specified by the prefix hex:, gets converted from hexadecimal form into a byte array form. this is how you do 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, ok? 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 to 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 (e.g. 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 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 🦋

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. yes queen 💅

🔮 Algorithm Specifiers 🔮

options that take algorithms support "nice-names". ngl this is lowkey the best part.

there are two major algorithm specification string classes: simple and complex. only certain algorithms get accepted by the TPM, based on usage and conditions. so like, read the room 🫠

⭐ 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 🧸

  • rsa
  • ecc

🎁 Symmetric 🎁

  • aes
  • camellia
  • sm4

🍯 Hashing Algorithms 🍯

  • sha1
  • sha256
  • sha384
  • sha512
  • sm3_256
  • sha3_256
  • sha3_384
  • sha3_512

🐝 Keyed Hash 🐝

  • hmac
  • xor

✍️ Signing Schemes ✍️

  • rsassa
  • rsapss
  • ecdsa
  • ecdaa
  • ecschnorr
  • sm2

🔒 Asymmetric Encryption Schemes 🔒

  • oaep
  • rsaes
  • ecdh

🔄 Modes 🔄

  • ctr
  • ofb
  • cbc
  • cfb
  • ecb

🎲 Misc 🎲

  • null

👑 Complex Specifiers 👑

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. the general format for specifying this data is:

<type>:<scheme>:<symmetric-details>

🌟 Type Specifiers 🌟

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. so the rest is optional, bestie 💁‍♀️

  • aes — default AES: aes128
  • aes128<mode> — 128 bit AES with optional mode (ctr|ofb|cbc|cfb|ecb). if mode is not specified, defaults to null.
  • aes192<mode> — same as aes128<mode>, except for a 192 bit key size.
  • aes256<mode> — same as aes128<mode>, except for a 256 bit key size.
  • sm4 — default SM4: sm4128
  • sm4128 or sm4_128 <mode> — 128 bit SM4 with optional mode (ctr|ofb|cbc|cfb|ecb). if mode is not specified, defaults to null.
  • ecc — Elliptical Curve, defaults to ecc256.
  • ecc192 or ecc_nist_p192 — 192 bit ECC NIST curve
  • ecc224 or ecc_nist_p224 — 224 bit ECC NIST curve
  • ecc256 or ecc_nist_p256 — 256 bit ECC NIST curve
  • ecc384 or ecc_nist_p384 — 384 bit ECC NIST curve
  • ecc521 or ecc_nist_p521 — 521 bit ECC NIST curve
  • ecc_sm2 or ecc_sm2_p256 — 256 bit SM2 curve
  • rsa — default RSA: rsa2048
  • rsa1024 — RSA with 1024 bit keysize.
  • rsa2048 — RSA with 2048 bit keysize.
  • rsa3072 — RSA with 3072 bit keysize.
  • rsa4096 — RSA with 4096 bit keysize.

💎 Scheme Specifiers 💎

next up is an optional field — you can skip it if you want, no pressure 🫶

schemes are usually Signing Schemes or Asymmetric Encryption Schemes. most signing schemes take a hash algorithm directly following the signing 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 algorithm. for example: oaep-sha256.

  • oaep
  • ecdh
  • rsassa
  • rsapss
  • ecdsa
  • ecschnorr
  • sm2

🌼 Multiple Option Scheme Specifiers 🌼

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.

🍀 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 its attributes. generally, any valid Symmetric specifier from the Type Specifiers list should work. if not specified, an asymmetric object's symmetric details default 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:ecdaa4-sha384 -u key.pub -r key.priv

cryptographic algorithms ALGORITHM. iconic 🔥

🎨 Object Attributes 🎨

Object Attributes are used to control various properties of created objects. 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 removing the prefix TPMA_OBJECT_ and lowercasing the result. so TPMA_OBJECT_FIXEDTPM becomes fixedtpm. slay 🎀 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.

🧬 PCR Bank Specifiers 🧬

PCR Bank Selection lists follow the below specification:

<BANK>:<PCR>[,<PCR>] or <BANK>:all

multiple banks may be separated by +. so like, stack 'em 💅

for example:

sha1:3,4+sha256:all

will select PCRs 3 and 4 from the SHA1 bank and PCRs 0 to 23 from the SHA256 bank. ate and left no crumbs 🍽️

certain commands support specifying forward sealing values as well:

sha1:0,1=da39a3ee5e6b4b0d3255bfef95601890afd80709,2

this will select the current values for PCRs 0 and 2, but use the specified value for PCR 1. digest lengths must match the bank size. an optional 0x prefix will be stripped off ✂️

🌙 Note 🌙

PCR Selections allow for up to 5 hash to pcr selection mappings. this is a limitation in design in the single call to the TPM to get the pcr values. not me being limited by the spec 😭

💅 COMMON OPTIONS

Okay bestie, this is the little grab-bag of options that basically every tool in the family supports — the stuff users just expect to be there. No cap. ✨

  • -h, --help=[man|no-man] — shows you the tool's manpage. By default it tries to fire up the manpager for the tool, and if that flops it'll just spit out a short tool summary instead. Same deal if you pass the man argument — except if you explicitly ask for man, the tool will hand you the errors from man on stderr (so you actually see what went wrong). If you pass no-man, or the manpager just isn't having it, the short options go to stdout. 🫶 To actually make the manpages feature work you need the manpages installed or sitting on MANPATH — go peek at man(1) for the deets.
  • -v, --version — prints version info for this tool plus the tctis it supports, then dips. 👋
  • -V, --verbose — turns up the volume on what the tool prints to the console while it runs. When this is on, the file and line number get printed too. 🔍
  • -Q, --quiet — silences normal tool output to stdout. shhh 🤫
  • -Z, --enable-errata — enables the application of errata fixups. Super useful if an errata fixup needs to be applied to the commands being sent to the TPM. Defining the env var TPM2TOOLS_ENABLE_ERRATA does the exact same thing. 🩹
  • -z, --pwd-session — uses a password session instead of a HMAC session for authentication. A clear text password gets passed to the TPM to authorize the action. This option is your bestie when you're dodging problems with unsalted sessions under OpenSSL FIPS mode. > Heads up though: 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, the transient parent object gets flushed too. You can also switch autoflush on by setting the env var TPM2TOOLS_AUTOFLUSH to yes or true. 🚽✨

🦋 TCTI Configuration

The TCTI — aka the "Transmission Interface" — is literally just the communication mechanism with the TPM. You can swap TCTIs around to talk to TPMs across all kinds of different mediums. iconic.

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

  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 always. 💅

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 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. Does not support ANY options and MUST BE presented as the exact text of none. no extras, no vibes, just 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-option-config> results in the default being used for that portion respectively. easy. 🎀

🌸 TCTI Defaults

When a TCTI isn't 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 tell you 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 like — this could be a path to the shared library, or a library name as understood by dlopen(3) semantics. slay, flexible. 🌈

🎀 TCTI OPTIONS

This collection of options configures the various known TCTI modules available:

  • device: for the device TCTI, you can specify the TPM character device file for the device TCTI to use. The default is /dev/tpm0.

Example: -T device:/dev/tpm0 or export TPM2TOOLS_TCTI=“device:/dev/tpm0”

  • mssim: for the mssim TCTI, you can specify the domain name or IP address and port number used by the simulator. The default 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. 💫

✨ EXAMPLES

To allocate the two default banks (SHA1 and SHA256)

tpm2_pcrallocate

To make a custom allocation with a platform authorization

tpm2_pcrallocate -P abc sha1:7,8,9,10,16,17,18,19+sha256:all

To completly switch from SHA1 bank to SHA256 with a platform authorization

tpm2_pcrallocate -P abc sha1:none+sha256:all

look at her go 😭💖

🔥 Returns

Tools can return any of the following codes:

  • 0 — Success. 🎉
  • 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 — take it to the issues, bestie. 🐛

🫶 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 — sourced from tpm2-tools and dated on the tpm2_pcrallocate(1) manpage footer. go allocate some PCRs, you absolute legend 💅✨🎀

📦 where this page comes from