fapi-profile - Man Page

See Also

fapi-config(5)

Description

FAPI Cryptographic Profile

Cryptographic profiles determine the cryptographic algorithms and parameters for all keys and operations of a specific TPM interaction. The values affected by these profiles are:

Two exemplary profiles for RSA and ECC are installed with the TSS. By default, the RSA cryptographic profile is activated. The user is free to create own cryptographic profiles according to his needs.

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:

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:

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:

Possible modes for symmetric encryption are:

Possible modes for the RSA decrypt scheme are:

The following curve ids can be used:

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

Colophon

This page is part of release 4.2.0 of Open Source implementation of the TCG TPM2 Software Stack (TSS2). A description of the project, information about reporting bugs, and the latest version of this page can be found at https://github.com/tpm2-software/tpm2-tss/.

License

This work is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0). For more information visit https://creativecommons.org/licenses/by/4.0/

Referenced By

fapi-config(5), tss2_authorizepolicy(1), tss2_changeauth(1), tss2_createkey(1), tss2_createnv(1), tss2_createseal(1), tss2_decrypt(1), tss2_delete(1), tss2_encrypt(1), tss2_exportkey(1), tss2_exportpolicy(1), tss2_getappdata(1), tss2_getcertificate(1), tss2_getdescription(1), tss2_getinfo(1), tss2_getplatformcertificates(1), tss2_getrandom(1), tss2_gettpm2object(1), tss2_gettpmblobs(1), tss2_import(1), tss2_list(1), tss2_nvextend(1), tss2_nvincrement(1), tss2_nvread(1), tss2_nvsetbits(1), tss2_nvwrite(1), tss2_pcrextend(1), tss2_pcrread(1), tss2_provision(1), tss2_quote(1), tss2_setappdata(1), tss2_setcertificate(1), tss2_setdescription(1), tss2_sign(1), tss2_unseal(1), tss2_verifyquote(1), tss2_verifysignature(1).

JULI 2020 TPM2 Software Stack