fapi-profile(5)

📦

version 4.2.0 · 8 versions

4.2.0 · arch rolling, nixos 26.05 (latest)
4.1.0 · opensuse-leap 16.0
3.2.3 · centos-stream 9
4.1.2 · alpine 3.24
4.1.5 · fedora 44
4.0.1 · ubuntu noble
3.2.1 · debian bookworm
4.1.3 · centos-stream 10, debian trixie, fedora 43, fedora 44, ubuntu questing, ubuntu resolute, ubuntu stonking

fapi-profile(5) 💖

okay bestie, welcome to the File Formats Manual for fapi-profile(5) — yes it's a file formats manual, yes it's giving ✨cryptographic configuration✨, and yes we're gonna get through all of it together. no skimming, no skipping. periodt. 🎀

👀 SEE ALSO

fapi-config(5)

✨ DESCRIPTION ✨

🌸 FAPI Cryptographic Profile 🌸

so basically, a cryptographic profile is the thing that decides which crypto algorithms and parameters get used for every single key and operation in one specific TPM interaction. like, it's the vibe-setter for the whole conversation with the TPM. 💅

the values that get affected by these profiles are:

the name hash algorithm
asymmetric signature algorithm, scheme and parameters (such as curve, keysize, default padding, hash, etc)
PCR bank selection (which PCR banks shall be extended, quoted and read)

Two exemplary profiles for RSA and ECC are installed with the TSS. By default, the RSA cryptographic profile is activated. And the user is free to create own cryptographic profiles according to his needs — go off, make your own, we love that for you. 🦋

Specific profiles are activated in the FAPI configuration file. If not otherwise specified during TSS installation, the default location for the exemplary profiles is /etc/tpm2-tss/profiles/ and /etc/tpm2-tss/ for the FAPI configuration file. 📁

🧚 The parameters of the profile are:

type: The asymmetric algorithm used for this profile.
nameAlg: The hash algorithm which will be used for sessions and keys.
srk_template: The type definition for the /SRK object. See the type parameter of Fapi_CreateKey.
srk_description: The description to be set for the /EK object. See Fapi_GetDescription.
ek_template: The type definition for the /EK object. See the type parameter of Fapi_CreateKey.
ek_description: The description to be set for the /SRK object. See Fapi_GetDescription.
ecc_signing_scheme: The signing scheme used for ECC keys.
rsa_signing_scheme: The signing scheme used for RSA keys.
keyBits: The key size for RSA keys.
exponent: The exponent of RSA keys.
sym_mode: The block cipher mode for symmetric encryption.
sym_parameters: The algorithm and parameters used for symmetric encryption.
sym_block_size: The block size used for symmetric encryption.
session_symmetric: The algorithm and parameters used for parameter encryption of a session (The same format and default as sym_parameters).
pcr_selection: The PCR registers and banks used by FAPI.
curveID: The curve ID for ECC keys.
ek_policy: The JSON encoded policy for the /EK object.
srk_policy: The JSON encoded policy for the /SRK object.
eh_policy: The JSON encoded policy for the endorsement hierarchy /HE.
sh_policy: The JSON encoded policy for the owner hierarchy /HS.
lockout_policy: The JSON encoded policy for the lockout hierarchy /LOCKOUT.
newMaxTries: Count of authorization failures before the lockout is imposed. If not set the default is 5.
newRecoveryTime: Time in seconds before the authorization failure count is automatically decremented. A value of zero indicates that DA protection is disabled. If not set the default is 1000.
lockoutRecovery: Time in seconds after a lockoutAuth failure before use of lockoutAuth is allowed A value of zero indicates that a reboot is required. If not set the default is 1000.
ignore_ek_template: Ignore EK template stored in NV ram. If not set the default is "no".

🌈 EXAMPLES 🌈

The following JSON encoded example shows the standard profile for ECC keys:

{
    "type": "ecc",
    "nameAlg":"sha256",
    "srk_template": "system,restricted,decrypt,0x81000001",
    "srk_description": "Storage root key SRK",
    "ek_template":  "system,restricted,decrypt",
    "ek_description": "Endorsement key EK",
    "ecc_signing_scheme": {
        "scheme":"ecdsa",
        "details":{
            "hashAlg":"sha256"
        },
    },
    "sym_mode":"cfb",
    "sym_parameters": {
        "algorithm":"aes",
        "keyBits":"128",
        "mode":"cfb"
    },
    "sym_block_size": 16,
    "pcr_selection": [
       { "hash": "sha1",
         "pcrSelect": [ ],
       },
       { "hash": "sha256",
         "pcrSelect": [ 8, 9, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 ]
       }
    ],
    "curveID": "nist_p256",
    "ek_policy": {
        "description": "Endorsement hierarchy used for policy secret.",
        "policy":[
            {
                "type":"policysecret",
                "objectName": "4000000b",
            }
        ]
    }
}

Beside the cryptographic parameters descriptions for the storage root key and the endorsement key can be set. For the endorsement hierarchy the policy "ek_policy" is set according to the TCG Credential profile EK 2.0. The values of the constants are the same as the constants defined in the TSS header files, where the prefix TPM2_ can be omitted. 🫶

The key type of the storage root key and the endorsement key is defined by the JSON fields srk_template and ek_template. The type consists of a list of comma and/or space separated keywords. If a keyword is not present the inverse of the reference TPM attribute bits SHALL be set or cleared. The keywords are:

sign: Sets the sign attribute of a key.
decrypt: Sets the decrypt attribute of a key.
If neither sign nor decrypt are provided, both attributes SHALL be set.
restricted: Sets the restricted attribute of a key.
If restricted is set, either sign or decrypt (but not both) SHALL be set.
noda: Sets the noda attribute of a key or NV index.
A hexadecimal number: Marks a key object to be made persistent and sets the persistent object handle to this value.
unique_zero=n: Initialization of the unique field with n zeros for RSA and for the x and y ECC unique field.
unique=hexstring: Initialization of the RSA unique field with a hextring (e.g. 0c0a0f0f0e).
unique_x=hexstring: Initialization of the ECC x unique field with a hextring (e.g. 0c0a0f0f0e).
unique_y=hexstring: Initialization of the ECC x unique field with a hextring (e.g. 0c0a0f0f0e).

The RSA profile has specific values for the signing scheme and the decrypt scheme:

            "rsa_signing_scheme": {
              "scheme":"rsapss",
              "details":{
                  "hashAlg":"sha256"
              }

          "rsa_decrypt_scheme": {
              "scheme":"oaep",
              "details":{
                  "hashAlg":"sha256"
              }
          },

Possible values for the signing schemes are:

RSA: RSASSA, RSAPSS
ECC: ECDSA, ECDAA

Possible modes for symmetric encryption are:

CTR, OFB, CBC, CFB, ECB, NULL

Possible modes for the RSA decrypt scheme are:

RSAES, OAEP

The following curve ids can be used:

ECC_NIST_P192, ECC_NIST_P224, ECC_NIST_P256, ECC_NIST_P384, ECC_NIST_P521, ECC_BN_P256, ECC_BN_P638, ECC_SM2_P256

If the PCR registers 0 to 10 are extended by BIOS and IMA in the SHA1 bank the following PCR selection should be used to enable the use of FAPI quote and verify quote:

   "pcr_selection": [
      { "hash": "sha1",
        "pcrSelect": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ],
      },
      { "hash": "sha256",
        "pcrSelect": [ 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23 ]
      }
   ],

The directory containing the FAPI profiles includes templates for various ECC and RSA keys. For ECC P-256 and RSA 2048-bit keys, there are three distinct profile templates. The .low-range profile corresponds to the low-range EK templates defined in the TCG EK Credential Profile and the TCG TPM 2.0 Provisioning Guidance. The .high-range profile corresponds to the high-range EK templates. The .legacy profile, currently the default, reflects the FAPI template used up to TSS version 4.1.3.

The table below illustrates the key differences:

low-range: noDa: 1, unique field set to zero (key size length).
high-range: noDa: 1, unique key size set to zero.
legacy: noDa: 0, unique key size set to zero.

🦋 Check existing SRK

In some cases, an SRK may already exist on the platform and can be reused by FAPI. This includes dual-boot setups and SRK initialization performed by systemd. The follwing script determines which FAPI profiles are appropriate for an existing SRK key.

#!/bin/bash
# It will be checked whether a FAPI profile in /etc/... exists
# which corresponds to the current persistent SRK with the
# handle 0x81000001

if ! command -v tss2_provision &> /dev/null; then
    echo "Error tss2_provisioning not installed."
    exit 1
fi

SRK_HANDLE=0x81000001

if tpm2_getcap handles-persistent| grep $SRK_HANDLE > /dev/null; then
    echo "Check SRK default handle $SRK_HANDLE"
else
    echo "Persistent SRK handle $SRK_HANDLE does not exist"
    exit 1
fi

PROFILES=( \
P_ECCP256SHA256-low-range \
P_RSA2048SHA256-low-range \
P_ECCP256SHA256-high-range \
P_RSA2048SHA256-high-range \
P_ECCP256SHA256-legacy \
P_RSA2048SHA256-legacy \
P_ECCP384SHA384 \
P_RSA3072SHA384 \
P_ECCP256SHA256 \
P_RSA2048SHA256 \
)

TMPDIR=$(mktemp -d)

USER_DIR="${TMPDIR}/tpm2-tss/user/keystore"
SYSTEM_DIR="${TMPDIR}/tpm2-tss/system/keystore"
LOG_DIR="${TMPDIR}/tpm2-tss/eventlog/"

for d in /usr/local/etc/tpm2-tss/fapi-profiles/ /etc/tpm2-tss/fapi-profiles/; do
    if [[ -d $d ]]; then
        PROFILE_DIR=$d
        break;
    fi
done

if [ -z "$PROFILE_DIR" ]; then
    echo "Profile dir not found"
    exit 1
fi

for PROFILE in "${PROFILES[@]}"; do
    config_file=${TMPDIR}/fapi_config.json
    cat <<EOF > "$config_file"
{
    "profile_name": "${PROFILE}",
    "profile_dir": "${PROFILE_DIR}",
    "user_dir": "${USER_DIR}",
    "system_dir": "${SYSTEM_DIR}",
    "tcti": "",
    "system_pcrs": [],
    "log_dir": "${LOG_DIR}",
    "firmware_log_file": "/sys/kernel/security/tpm0/binary_bios_measurements",
    "ima_log_file": "/sys/kernel/security/ima/binary_runtime_measurements"
}
EOF
    export TSS2_FAPICONF="$config_file"
    if tss2_provision > /dev/null 2>&1 ;then
        echo "+ ${PROFILE} provisioned"
    else
        echo "- ${PROFILE} failed"
    fi
    rm "$config_file"
    rm -r -f $TMPDIR/tmp2-tss
done
rm -r -f $TMPDIR
fi

and bestie… that's only part 1 🫢 there's MORE coming, don't go anywhere 💖

💖 COLOPHON 💖

okay bestie, housekeeping era 🧹✨ this page is part of release 4.2.0 of the Open Source implementation of the TCG TPM2 Software Stack (TSS2). that's the whole vibe of where you are rn 🫶

want the tea on the project itself? the deets on how to snitch about bugs (affectionately)? or just the freshest, most up-to-date version of this very page? it's all sitting right here:

https://github.com/tpm2-software/tpm2-tss/

go forth and bookmark it, no cap 📌

🎀 LICENSE 🎀

this work is licensed under the Creative Commons Attribution 4.0 International License (aka CC BY 4.0). yes she's open, yes she's shareable, she's giving generous icon energy 💅

for the full legal read (it's giving very demure, very mindful, very lawyer), pull up:

https://creativecommons.org/licenses/by/4.0/

and that's a wrap on fapi-profile(5), babes 🎬💖 this lil masterpiece came to you from the TPM2 Software Stack, dated JULI 2020, release 4.2.0 — yeah she's an elder but she ATE and left no crumbs 👑 go forth, profile those TPMs, and stay iconic 🦋✨

📦 where this page comes from

arch rolling: tpm2-tss 4.2.0-2 · BSD-2-Clause
nixos 26.05: tpm2-tss 4.2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-18: a language model's rewrite of the original, under its terms