B. Algorithm and key type encoding¶

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

Algorithm identifier encoding describes the encoding scheme for algorithm identifiers
Key type encoding describes the encoding scheme for key types

B.1. 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 2.

../_images/algorithm_fields.svg — Figure 2 Encoding of `psa_algorithm_t`¶

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

Table 9 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.

B.1.1. Algorithm categories¶

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

Table 10 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

B.1.2. Hash algorithm encoding¶

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

../_images/hash_fields.svg — Figure 3 Hash algorithm encoding¶

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

Table 11 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`

The wildcard hash PSA_ALG_ANY_HASH can be used to parameterize a signature algorithm which defines a key usage policy, permitting any hash algorithm to be specified in a signature operation using the key.

B.1.3. MAC algorithm encoding¶

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

../_images/mac_fields.svg — Figure 4 MAC algorithm encoding¶

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

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 11) for hash-based MAC algorithms, otherwise H = 0.

Table 12 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

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.
hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the MAC algorithm.
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.

B.1.4. Cipher algorithm encoding¶

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

../_images/cipher_fields.svg — Figure 5 CIPHER algorithm encoding¶

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

Table 13 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`

The stream cipher algorithm identifier PSA_ALG_STREAM_CIPHER is used with specific stream cipher key types, such as PSA_KEY_TYPE_CHACHA20.
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.

B.1.5. AEAD algorithm encoding¶

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

../_images/aead_fields.svg — Figure 6 AEAD algorithm encoding¶

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

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 14 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

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

B.1.6. Key derivation algorithm encoding¶

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

../_images/kdf_fields.svg — Figure 7 Key derivation algorithm encoding¶

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

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

Table 15 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
HKDF-Extract	0	`0x04`	`PSA_ALG_HKDF_EXTRACT(hash_alg)`	`0x080004hh` ^a
HKDF-Expand	0	`0x05`	`PSA_ALG_HKDF_EXPAND(hash_alg)`	`0x080005hh` ^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`

hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the key derivation algorithm.

B.1.7. Asymmetric signature algorithm encoding¶

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

../_images/sign_fields.svg — Figure 8 Asymmetric signature algorithm encoding¶

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

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

Table 16 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

hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the signature algorithm.
Asymmetric signature algorithms without hashing can only be used with psa_sign_hash() and psa_verify_hash().
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.

B.1.8. Asymmetric encryption algorithm encoding¶

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

../_images/pke_fields.svg — Figure 9 Asymmetric encryption algorithm encoding¶

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

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

Table 17 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

hh is the HASH-TYPE for the hash algorithm, hash_alg, used to construct the encryption algorithm.

B.1.9. 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 10.

../_images/ka_raw_fields.svg — Figure 10 Raw key agreement algorithm encoding¶

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

Table 18 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 11 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.

B.2. 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 12.

../_images/key_type_fields.svg — Figure 12 Encoding of `psa_key_type_t`¶

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

Table 19 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.

B.2.1. Key type categories¶

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

Table 20 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

B.2.2. Raw key encoding¶

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

../_images/raw_key_fields.svg — Figure 13 Raw key encoding¶

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

Table 21 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`

B.2.3. Symmetric key encoding¶

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

../_images/symmetric_key_fields.svg — Figure 14 Symmetric key encoding¶

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

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

Table 22 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`

B.2.4. Asymmetric key encoding¶

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

../_images/asymmetric_key_fields.svg — Figure 15 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 23.

Table 23 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 16.

../_images/rsa_key_fields.svg — Figure 16 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 24.

Table 24 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 17.

../_images/ecc_key_fields.svg — Figure 17 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 25.

Table 25 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`

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 18.

../_images/dh_key_fields.svg — Figure 18 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 26.

Table 26 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`

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.