| .\" 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 |