man/fapi-profile.5.in

.\" Automatically generated by Pandoc 1.19.2.1
.\"
.TH "fapi-profile" 5 "JULI 2020" "TPM2 Software Stack"
.hy
.SH "SEE ALSO"
.BR fapi-config (5)
.SH DESCRIPTION
.PP
.SB FAPI Cryptographic Profile
.PP
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:
.IP \[bu] 2
the name hash algorithm
.IP \[bu] 2
asymmetric signature algorithm, scheme and parameters (such as curve,
keysize, default padding, hash, etc)
.IP \[bu] 2
PCR bank selection (which PCR banks shall be extended, quoted and read)
.PP
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.
.PP
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.
.PP
The parameters of the profile are:
.IP \[bu] 2
type: The asymmetric algorithm used for this profile.
.IP \[bu] 2
nameAlg: The hash algorithm which will be used for sessions and keys.
.IP \[bu] 2
srk_template: The type definition for the /SRK object.
See the type parameter of Fapi_CreateKey.
.IP \[bu] 2
srk_description: The description to be set for the /EK object.
See Fapi_GetDescription.
.IP \[bu] 2
ek_template: The type definition for the /EK object.
See the type parameter of Fapi_CreateKey.
.IP \[bu] 2
ek_description: The description to be set for the /SRK object.
See Fapi_GetDescription.
.IP \[bu] 2
ecc_signing_scheme: The signing scheme used for ECC keys.
.IP \[bu] 2
rsa_signing_scheme: The signing scheme used for RSA keys.
.IP \[bu] 2
keyBits: The key size for RSA keys.
.IP \[bu] 2
exponent: The exponent of RSA keys.
.IP \[bu] 2
sym_mode: The block cipher mode for symmetric encryption.
.IP \[bu] 2
sym_parameters: The algorithm and parameters used for symmetric
encryption.
.IP \[bu] 2
sym_block_size: The block size used for symmetric encryption.
.IP \[bu] 2
pcr_selection: The PCR registers and banks used by FAPI.
.IP \[bu] 2
curveID: The curve ID for ECC keys.
.IP \[bu] 2
ek_policy: The JSON encoded policy for the /EK object.
.IP \[bu] 2
srk_policy: The JSON encoded policy for the /SRK object.
.IP \[bu] 2
eh_policy: The JSON encoded policy for the endorsement hierarchy /HE.
.IP \[bu] 2
sh_policy: The JSON encoded policy for the owner hierarchy /HS.
.IP \[bu] 2
lockout_policy: The JSON encoded policy for the lockout hierarchy
/LOCKOUT.
.IP \[bu] 2
newMaxTries: Count of authorization failures before the lockout is
imposed.
If not set the default is 5.
.IP \[bu] 2
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.
.IP \[bu] 2
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.
.SH EXAMPLES
.PP
The following JSON encoded example shows the standard profile for ECC
keys:
.IP
.nf
\f[C]
{
\ \ \ \ "type":\ "TPM2_ALG_ECC",
\ \ \ \ "nameAlg":"TPM2_ALG_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":"TPM2_ALG_ECDSA",
\ \ \ \ \ \ \ \ "details":{
\ \ \ \ \ \ \ \ \ \ \ \ "hashAlg":"TPM2_ALG_SHA256"
\ \ \ \ \ \ \ \ },
\ \ \ \ },
\ \ \ \ "sym_mode":"TPM2_ALG_CFB",
\ \ \ \ "sym_parameters":\ {
\ \ \ \ \ \ \ \ "algorithm":"TPM2_ALG_AES",
\ \ \ \ \ \ \ \ "keyBits":"128",
\ \ \ \ \ \ \ \ "mode":"TPM2_ALG_CFB"
\ \ \ \ },
\ \ \ \ "sym_block_size":\ 16,
\ \ \ \ "pcr_selection":\ [
\ \ \ \ \ \ \ {\ "hash":\ "TPM2_ALG_SHA1",
\ \ \ \ \ \ \ \ \ "pcrSelect":\ [\ ],
\ \ \ \ \ \ \ },
\ \ \ \ \ \ \ {\ "hash":\ "TPM2_ALG_SHA256",
\ \ \ \ \ \ \ \ \ "pcrSelect":\ [\ 8,\ 9,\ 11,\ 12,\ 13,\ 14,\ 15,\ 16,\ 17,\ 18,\ 19,\ 20,\ 21,\ 22,\ 23\ ]
\ \ \ \ \ \ \ }
\ \ \ \ ],
\ \ \ \ "curveID":\ "TPM2_ECC_NIST_P256",
\ \ \ \ "ek_policy":\ {
\ \ \ \ \ \ \ \ "description":\ "Endorsement\ hierarchy\ used\ for\ policy\ secret.",
\ \ \ \ \ \ \ \ "policy":[
\ \ \ \ \ \ \ \ \ \ \ \ {
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "type":"POLICYSECRET",
\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ "objectName":\ "4000000b",
\ \ \ \ \ \ \ \ \ \ \ \ }
\ \ \ \ \ \ \ \ ]
\ \ \ \ }
}
\f[]
.fi
.PP
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.
.PP
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:
.IP \[bu] 2
sign: Sets the sign attribute of a key.
.IP \[bu] 2
decrypt: Sets the decrypt attribute of a key.
.IP \[bu] 2
If neither sign nor decrypt are provided, both attributes SHALL be set.
.IP \[bu] 2
restricted: Sets the restricted attribute of a key.
.IP \[bu] 2
If restricted is set, either sign or decrypt (but not both) SHALL be
set.
.IP \[bu] 2
noda: Sets the noda attribute of a key or NV index.
.IP \[bu] 2
A hexadecimal number: Marks a key object to be made persistent and sets
the persistent object handle to this value.
.PP
The RSA profile has specific values for the signing scheme and the
decrypt scheme:
.IP
.nf
\f[C]
\ \ \ \ \ \ "rsa_signing_scheme":\ {
\ \ \ \ \ \ \ \ "scheme":"TPM2_ALG_RSAPSS",
\ \ \ \ \ \ \ \ "details":{
\ \ \ \ \ \ \ \ \ \ \ \ "hashAlg":"TPM2_ALG_SHA256"
\ \ \ \ \ \ \ \ }


\ \ \ \ "rsa_decrypt_scheme":\ {
\ \ \ \ \ \ \ \ "scheme":"TPM2_ALG_OAEP",
\ \ \ \ \ \ \ \ "details":{
\ \ \ \ \ \ \ \ \ \ \ \ "hashAlg":"TPM2_ALG_SHA256"
\ \ \ \ \ \ \ \ }
\ \ \ \ },
\f[]
.fi
.PP
Possible values for the signing schemes are:
.IP \[bu] 2
RSA: RSASSA, RSAPSS
.IP \[bu] 2
ECC: ECDSA, ECDAA
.PP
Possible modes for symmetric encryption are:
.IP \[bu] 2
CTR, OFB, CBC, CFB, ECB, NULL
.PP
Possible modes for the RSA decrypt scheme are:
.IP \[bu] 2
RSAES, OAEP
.PP
The following curve ids can be used:
.IP \[bu] 2
ECC_NIST_P192, ECC_NIST_P224, ECC_NIST_P256, ECC_NIST_P384,
ECC_NIST_P521, ECC_BN_P256, ECC_BN_P638, ECC_SM2_P256