Algorithm and key type encoding

Algorithm identifiers (psa_algorithm_t) and key types (psa_key_type_t) in the PSA Crypto API are structured integer values.

Algorithm identifier encoding

Algorithm identifiers are 32-bit integer values of the type psa_algorithm_t. Algorithm identifier values have the structure shown in Figure 1.

../_images/algorithm_fields.svg

Figure 1 Encoding of psa_algorithm_t

Table 6 describes the meaning of the bit-fields — some of the bit-fields are used in different ways by different algorithm categories.

Table 6 Bit fields in an algorithm identifier
Field Bits Description
V [31]

Flag to indicate an implementation-defined algorithm identifier, when V=1.

Algorithm identifiers defined by this specification always have V=0.

CAT [30:24] Algorithm category. See Algorithm categories.
S [23]

For a cipher algorithm, this flag indicates a stream cipher when S=1.

For a key derivation algorithm, this flag indicates a key-stretching or password-hashing algorithm when S=1.

B [22] Flag to indicate an algorithm built on a block cipher, when B=1.
LEN/T2 [21:16] LEN is the length of a MAC or AEAD tag, T2 is a key agreement algorithm sub-type.
T1 [15:8] Algorithm sub-type for most algorithm categories.
H [7:0] Hash algorithm sub-type, also used in any algorithm that is parameterized by a hash.

Algorithm categories

The CAT field in an algorithm identifier takes the values shown in Table 7.

Table 7 Algorithm identifier categories
Algorithm category CAT Category details
None 0x00 See PSA_ALG_NONE
Hash 0x02 See Hash algorithm encoding
MAC 0x03 See MAC algorithm encoding
Cipher 0x04 See Cipher algorithm encoding
AEAD 0x05 See AEAD algorithm encoding
Key derivation 0x08 See Key derivation algorithm encoding
Asymmetric signature 0x06 See Asymmetric signature algorithm encoding
Asymmetric encryption 0x07 See Asymmetric encryption algorithm encoding
Key agreement 0x09 See Key agreement algorithm encoding

Hash algorithm encoding

The algorithm identifier for hash algorithms defined in this specification are encoded as shown in Figure 2.

../_images/hash_fields.svg

Figure 2 Hash algorithm encoding

The defined values for HASH-TYPE are shown in Table 8.

Table 8 Hash algorithm sub-type values
Hash algorithm HASH-TYPE Algorithm identifier Algorithm value
MD2 0x01 PSA_ALG_MD2 0x02000001
MD4 0x02 PSA_ALG_MD4 0x02000002
MD5 0x03 PSA_ALG_MD5 0x02000003
RIPEMD-160 0x04 PSA_ALG_RIPEMD160 0x02000004
SHA1 0x05 PSA_ALG_SHA_1 0x02000005
SHA-224 0x08 PSA_ALG_SHA_224 0x02000008
SHA-256 0x09 PSA_ALG_SHA_256 0x02000009
SHA-384 0x0A PSA_ALG_SHA_384 0x0200000A
SHA-512 0x0B PSA_ALG_SHA_512 0x0200000B
SHA-512/224 0x0C PSA_ALG_SHA_512_224 0x0200000C
SHA-512/256 0x0D PSA_ALG_SHA_512_256 0x0200000D
SHA3-224 0x10 PSA_ALG_SHA3_224 0x02000010
SHA3-256 0x11 PSA_ALG_SHA3_256 0x02000011
SHA3-384 0x12 PSA_ALG_SHA3_384 0x02000012
SHA3-512 0x13 PSA_ALG_SHA3_512 0x02000013
SM3 0x14 PSA_ALG_SM3 0x02000014
SHAKE256-512 0x15 PSA_ALG_SHAKE256_512 0x02000015
wildcard a 0xFF PSA_ALG_ANY_HASH 0x020000FF
  1. The wildcard hash PSA_ALG_ANY_HASH can be used to parameterize a signature algorithm which defines a key usage policy, allowing any hash algorithm to be specified in a signature operation using the key.

MAC algorithm encoding

The algorithm identifier for MAC algorithms defined in this specification are encoded as shown in Figure 3.

../_images/mac_fields.svg

Figure 3 MAC algorithm encoding

The defined values for B and MAC-TYPE are shown in Table 9.

LEN = 0 specifies a default length output MAC, other values for LEN specify a truncated MAC.

W is a flag to indicate a wildcard permitted-algorithm policy:

  • W = 0 indicates a specific MAC algorithm and MAC length.
  • W = 1 indicates a wildcard key usage policy, which permits the MAC algorithm with a MAC length of at least LEN to be specified in a MAC operation using the key. LEN must not be zero.

H = HASH-TYPE (see Table 8) for hash-based MAC algorithms, otherwise H = 0.

Table 9 MAC algorithm sub-type values
MAC algorithm B MAC-TYPE Algorithm identifier Algorithm value
HMAC 0 0x00 PSA_ALG_HMAC(hash_alg) 0x038000hh a b
CBC-MAC c 1 0x01 PSA_ALG_CBC_MAC 0x03c00100 a
CMAC c 1 0x02 PSA_ALG_CMAC 0x03c00200 a
  1. This is the default algorithm identifier, specifying a standard length tag. PSA_ALG_TRUNCATED_MAC() generates identifiers with non-default LEN values. PSA_ALG_AT_LEAST_THIS_LENGTH_MAC() generates permitted-algorithm policies with W = 1.
  2. hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the MAC algorithm.
  3. This is a MAC constructed using an underlying block cipher. The block cipher is determined by the key type that is provided to the MAC operation.

Cipher algorithm encoding

The algorithm identifier for CIPHER algorithms defined in this specification are encoded as shown in Figure 4.

../_images/cipher_fields.svg

Figure 4 CIPHER algorithm encoding

The defined values for S, B, and CIPHER-TYPE are shown in Table 10.

Table 10 Cipher algorithm sub-type values
Cipher algorithm S B CIPHER-TYPE Algorithm identifier Algorithm value
Stream cipher a 1 0 0x01 PSA_ALG_STREAM_CIPHER 0x04800100
CTR mode b 1 1 0x10 PSA_ALG_CTR 0x04C01000
CFB mode b 1 1 0x11 PSA_ALG_CFB 0x04C01100
OFB mode b 1 1 0x12 PSA_ALG_OFB 0x04C01200
XTS mode b 0 1 0xFF PSA_ALG_XTS 0x0440FF00
CBC mode without padding b 0 1 0x40 PSA_ALG_CBC_NO_PADDING 0x04404000
CBC mode with PKCS#7 padding b 0 1 0x41 PSA_ALG_CBC_PKCS7 0x04404100
ECB mode without padding b 0 1 0x44 PSA_ALG_ECB_NO_PADDING 0x04404400
  1. The stream cipher algorithm identifier PSA_ALG_STREAM_CIPHER is used with specific stream cipher key types, such as PSA_KEY_TYPE_CHACHA20.
  2. This is a cipher mode of an underlying block cipher. The block cipher is determined by the key type that is provided to the cipher operation.

AEAD algorithm encoding

The algorithm identifier for AEAD algorithms defined in this specification are encoded as shown in Figure 5.

../_images/aead_fields.svg

Figure 5 AEAD algorithm encoding

The defined values for B and AEAD-TYPE are shown in Table 11.

LEN = 1..31 specifies the output tag length.

W is a flag to indicate a wildcard permitted-algorithm policy:

  • W = 0 indicates a specific AEAD algorithm and tag length.
  • W = 1 indicates a wildcard key usage policy, which permits the AEAD algorithm with a tag length of at least LEN to be specified in an AEAD operation using the key.
Table 11 AEAD algorithm sub-type values
AEAD algorithm B AEAD-TYPE Algorithm identifier Algorithm value
CCM a 1 0x01 PSA_ALG_CCM 0x05500100 b
GCM a 1 0x02 PSA_ALG_GCM 0x05500200 b
ChaCha20-poly1305 0 0x05 PSA_ALG_CHACHA20_POLY1305 0x05100500 b
  1. This is an AEAD mode of an underlying block cipher. The block cipher is determined by the key type that is provided to the AEAD operation.
  2. This is the default algorithm identifier, specifying the default tag length for the algorithm. PSA_ALG_AEAD_WITH_SHORTENED_TAG() generates identifiers with alternative LEN values. PSA_ALG_AEAD_WITH_AT_LEAST_THIS_LENGTH_TAG() generates wildcard permitted-algorithm policies with W = 1.

Key derivation algorithm encoding

The algorithm identifier for key derivation algorithms defined in this specification are encoded as shown in Figure 6.

../_images/kdf_fields.svg

Figure 6 Key derivation algorithm encoding

The defined values for S and KDF-TYPE are shown in Table 12.

The permitted values of HASH-TYPE (see Table 8) depend on the specific KDF algorithm.

Table 12 Key derivation algorithm sub-type values
Key derivation algorithm S KDF-TYPE Algorithm identifier Algorithm value
HKDF 0 0x01 PSA_ALG_HKDF(hash_alg) 0x080001hh a
TLS-1.2 PRF 0 0x02 PSA_ALG_TLS12_PRF(hash_alg) 0x080002hh a
TLS-1.2 PSK-to-MasterSecret 0 0x03 PSA_ALG_TLS12_PSK_TO_MS(hash_alg) 0x080003hh a
PBKDF2-HMAC 1 0x01 PSA_ALG_PBKDF2_HMAC(hash_alg) 0x088001hh a
PBKDF2-AES-CMAC-PRF-128 1 0x02 PSA_ALG_PBKDF2_AES_CMAC_PRF_128 0x08800200
  1. hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the key derivation algorithm.

Asymmetric signature algorithm encoding

The algorithm identifier for asymmetric signature algorithms defined in this specification are encoded as shown in Figure 7.

../_images/sign_fields.svg

Figure 7 Asymmetric signature algorithm encoding

The defined values for SIGN-TYPE are shown in Table 13.

H = HASH-TYPE (see Table 8) for message signature algorithms that are parameterized by a hash algorithm, otherwise H = 0.

Table 13 Asymmetric signature algorithm sub-type values
Signature algorithm SIGN-TYPE Algorithm identifier Algorithm value
RSA PKCS#1 v1.5 0x02 PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg) 0x060002hh a
RSA PKCS#1 v1.5 no hash b 0x02 PSA_ALG_RSA_PKCS1V15_SIGN_RAW 0x06000200
RSA PSS 0x03 PSA_ALG_RSA_PSS(hash_alg) 0x060003hh a
RSA PSS any salt length 0x13 PSA_ALG_RSA_PSS_ANY_SALT(hash_alg) 0x060013hh a
Randomized ECDSA 0x06 PSA_ALG_ECDSA(hash_alg) 0x060006hh a
Randomized ECDSA no hash b 0x06 PSA_ALG_ECDSA_ANY 0x06000600
Deterministic ECDSA 0x07 PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) 0x060007hh a
PureEdDSA 0x08 PSA_ALG_PURE_EDDSA 0x06000800
HashEdDSA 0x09 PSA_ALG_ED25519PH and PSA_ALG_ED448PH 0x060009hh c
  1. hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the signature algorithm.
  2. Asymmetric signature algorithms without hashing can only be used with psa_sign_hash() and psa_verify_hash().
  3. The HASH-TYPE for HashEdDSA is determined by the curve. SHA-512 is used for Ed25519ph, and the first 64 bytes of output from SHAKE256 is used for Ed448ph.

Asymmetric encryption algorithm encoding

The algorithm identifier for asymmetric encryption algorithms defined in this specification are encoded as shown in Figure 8.

../_images/pke_fields.svg

Figure 8 Asymmetric encryption algorithm encoding

The defined values for ENCRYPT-TYPE are shown in Table 14.

H = HASH-TYPE (see Table 8) for asymmetric encryption algorithms that are parameterized by a hash algorithm, otherwise H = 0.

Table 14 Asymmetric encryption algorithm sub-type values
Asymmetric encryption algorithm ENCRYPT-TYPE Algorithm identifier Algorithm value
RSA PKCS#1 v1.5 0x02 PSA_ALG_RSA_PKCS1V15_CRYPT 0x07000200
RSA OAEP 0x03 PSA_ALG_RSA_OAEP(hash_alg) 0x070003hh a
  1. hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the encryption algorithm.

Key agreement algorithm encoding

A key agreement algorithm identifier can either be for the raw key agreement algorithm, or for a combined key agreement with key derivation algorithm. The former can only be used with psa_raw_key_agreement(), while the latter are used with psa_key_derivation_key_agreement() and the shared secret is not exposed to the client.

The algorithm identifier for raw key agreement algorithms defined in this specification are encoded as shown in Figure 9.

../_images/ka_raw_fields.svg

Figure 9 Raw key agreement algorithm encoding

The defined values for KA-TYPE are shown in Table 15.

Table 15 Key agreement algorithm sub-type values
Key agreement algorithm KA-TYPE Algorithm identifier Algorithm value
FFDH 0x01 PSA_ALG_FFDH 0x09010000
ECDH 0x02 PSA_ALG_ECDH 0x09020000

A combined key agreement is constructed by a bitwise OR of the raw key agreement algorithm identifier and the key derivation algorithm identifier. This operation is provided by the PSA_ALG_KEY_AGREEMENT() macro.

../_images/ka_combined_fields.svg

Figure 10 Combined key agreement algorithm encoding

The underlying raw key agreement algorithm can be extracted from the KA-TYPE field, and the key derivation algorithm from the KDF-TYPE and HASH-TYPE fields.

Key type encoding

Key types are 16-bit integer values of the type psa_key_type_t. Key type values have the structure shown in Figure 11.

../_images/key_type_fields.svg

Figure 11 Encoding of psa_key_type_t

Table 16 describes the meaning of the bit-fields — some of bit-fields are used in different ways by different key type categories.

Table 16 Bit fields in a key type
Field Bits Description
V [15]

Flag to indicate an implementation-defined key type, when V=1.

Key types defined by this specification always have V=0.

A [14] Flag to indicate an asymmetric key type, when A=1.
CAT [13:12] Key type category. See Key type categories.
category-specific type [11:1] The meaning of this field is specific to each key category.
P [0] Parity bit. Valid key type values have even parity.

Key type categories

The A and CAT fields in a key type take the values shown in Table 17.

Table 17 Key type categories
Key type category A CAT Category details
None 0 0 See PSA_KEY_TYPE_NONE
Raw data 0 1 See Raw key encoding
Symmetric key 0 2 See Symmetric key encoding
Asymmetric public key 1 0 See Asymmetric key encoding
Asymmetric key pair 1 3 See Asymmetric key encoding

Raw key encoding

The key type for raw keys defined in this specification are encoded as shown in Figure 12.

../_images/raw_key_fields.svg

Figure 12 Raw key encoding

The defined values for RAW-TYPE, SUB-TYPE, and P are shown in Table 18.

Table 18 Raw key sub-type values
Raw key type RAW-TYPE SUB-TYPE P Key type Key type value
Raw data 0 0 1 PSA_KEY_TYPE_RAW_DATA 0x1001
HMAC 1 0 0 PSA_KEY_TYPE_HMAC 0x1100
Derivation secret 2 0 0 PSA_KEY_TYPE_DERIVE 0x1200
Password 2 1 1 PSA_KEY_TYPE_PASSWORD 0x1203
Password hash 2 2 1 PSA_KEY_TYPE_PASSWORD_HASH 0x1205
Derivation pepper 2 3 0 PSA_KEY_TYPE_PEPPER 0x1206

Symmetric key encoding

The key type for symmetric keys defined in this specification are encoded as shown in Figure 13.

../_images/symmetric_key_fields.svg

Figure 13 Symmetric key encoding

For block-based cipher keys, the block size for the cipher algorithm is 2BLK.

The defined values for BLK, SYM-TYPE and P are shown in Table 19.

Table 19 Symmetric key sub-type values
Symmetric key type BLK SYM-TYPE P Key type Key type value
ARC4 0 1 0 PSA_KEY_TYPE_ARC4 0x2002
ChaCha20 0 2 0 PSA_KEY_TYPE_CHACHA20 0x2004
DES 3 0 1 PSA_KEY_TYPE_DES 0x2301
AES 4 0 0 PSA_KEY_TYPE_AES 0x2400
CAMELLIA 4 1 1 PSA_KEY_TYPE_CAMELLIA 0x2403
SM4 4 2 1 PSA_KEY_TYPE_SM4 0x2405
ARIA 4 3 0 PSA_KEY_TYPE_ARIA 0x2406

Asymmetric key encoding

The key type for asymmetric keys defined in this specification are encoded as shown in Figure 14.

../_images/asymmetric_key_fields.svg

Figure 14 Asymmetric key encoding

PAIR is either 0 for a public key, or 3 for a key pair.

The defined values for ASYM-TYPE are shown in Table 20.

Table 20 Asymmetric key sub-type values
Asymmetric key type ASYM-TYPE Details
RSA 0 See RSA key encoding
Elliptic Curve 1 See Elliptic Curve key encoding
Diffie-Hellman 2 See Diffie Hellman key encoding

RSA key encoding

The key type for RSA keys defined in this specification are encoded as shown in Figure 15.

../_images/rsa_key_fields.svg

Figure 15 RSA key encoding

PAIR is either 0 for a public key, or 3 for a key pair.

The defined values for RSA keys are shown in Table 21.

Table 21 RSA key values
RSA key type Key type Key type value
Public key PSA_KEY_TYPE_RSA_PUBLIC_KEY 0x4001
Key pair PSA_KEY_TYPE_RSA_KEY_PAIR 0x7001

Elliptic Curve key encoding

The key type for Elliptic Curve keys defined in this specification are encoded as shown in Figure 16.

../_images/ecc_key_fields.svg

Figure 16 Elliptic Curve key encoding

PAIR is either 0 for a public key, or 3 for a key pair.

The defined values for ECC-FAMILY and P are shown in Table 22.

Table 22 ECC key family values
ECC key family ECC-FAMILY P ECC family a Public key value Key pair value
SECP K1 0x0B 1 PSA_ECC_FAMILY_SECP_K1 0x4117 0x7117
SECP R1 0x09 0 PSA_ECC_FAMILY_SECP_R1 0x4112 0x7112
SECP R2 0x0D 1 PSA_ECC_FAMILY_SECP_R2 0x411B 0x711B
SECT K1 0x13 1 PSA_ECC_FAMILY_SECT_K1 0x4127 0x7127
SECT R1 0x11 0 PSA_ECC_FAMILY_SECT_R1 0x4122 0x7122
SECT R2 0x15 1 PSA_ECC_FAMILY_SECT_R2 0x412B 0x712B
Brainpool-P R1 0x18 0 PSA_ECC_FAMILY_BRAINPOOL_P_R1 0x4130 0x7130
FRP 0x19 1 PSA_ECC_FAMILY_FRP 0x4133 0x7133
Montgomery 0x20 1 PSA_ECC_FAMILY_MONTGOMERY 0x4141 0x7141
Twisted Edwards 0x21 0 PSA_ECC_FAMILY_TWISTED_EDWARDS 0x4142 0x7142
  1. The key type value is constructed from the Elliptic Curve family using either PSA_KEY_TYPE_ECC_PUBLIC_KEY(family) or PSA_KEY_TYPE_ECC_KEY_PAIR(family) as required.

Diffie Hellman key encoding

The key type for Diffie Hellman keys defined in this specification are encoded as shown in Figure 17.

../_images/dh_key_fields.svg

Figure 17 Diffie Hellman key encoding

PAIR is either 0 for a public key, or 3 for a key pair.

The defined values for DH-FAMILY and P are shown in Table 23.

Table 23 Diffie Hellman key group values
DH key group DH-FAMILY P DH group a Public key value Key pair value
RFC7919 0x01 1 PSA_DH_FAMILY_RFC7919 0x4203 0x7203
  1. The key type value is constructed from the Diffie Hellman family using either PSA_KEY_TYPE_DH_PUBLIC_KEY(family) or PSA_KEY_TYPE_DH_KEY_PAIR(family) as required.