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.

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.

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
AES-MMO (Zigbee)	0x07	PSA_ALG_AES_MMO_ZIGBEE	0x02000007
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, 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.

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

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.

B.1.4. Cipher algorithm encoding

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

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
CCM* with zero-length tag b	1	1	0x13	PSA_ALG_CCM_STAR_NO_TAG	0x04C01300
CCM* wildcard c	1	1	0x93	PSA_ALG_CCM_STAR_ANY_TAG	0x04c09300
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.

3. The wildcard algorithm PSA_ALG_CCM_STAR_ANY_TAG permits a key to be used with any CCM* algorithm: unauthenticated cipher PSA_ALG_CCM_STAR_NO_TAG, and AEAD algorithm PSA_ALG_CCM.

B.1.5. AEAD algorithm encoding

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

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
XChaCha20-Poly1305	0	0x06	PSA_ALG_XCHACHA20_POLY1305	0x05100600 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.

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.

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)	0x080001hh a
TLS-1.2 PRF	0	0x02	PSA_ALG_TLS12_PRF(hash)	0x080002hh a
TLS-1.2 PSK-to-MasterSecret	0	0x03	PSA_ALG_TLS12_PSK_TO_MS(hash)	0x080003hh a
HKDF-Extract	0	0x04	PSA_ALG_HKDF_EXTRACT(hash)	0x080004hh a
HKDF-Expand	0	0x05	PSA_ALG_HKDF_EXPAND(hash)	0x080005hh a
TLS 1.2 ECJPAKE-to-PMS	0	0x06	PSA_ALG_TLS12_ECJPAKE_TO_PMS	0x08000609
SP 800-108 Counter HMAC	0	0x07	PSA_ALG_SP800_108_COUNTER_HMAC(hash)	0x080007hh a
SP 800-108 Counter CMAC	0	0x08	PSA_ALG_SP800_108_COUNTER_CMAC	0x08000800
PBKDF2-HMAC	1	0x01	PSA_ALG_PBKDF2_HMAC(hash)	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, 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.

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

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.

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.

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

1. 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 standalone key agreement algorithm, or for a combined key agreement with key derivation algorithm. The former can only be used with psa_key_agreement() and psa_raw_key_agreement(), while the latter are used with psa_key_derivation_key_agreement().

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

Figure 10 Standalone 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 standalone key agreement algorithm identifier and the key derivation algorithm identifier. This operation is provided by the PSA_ALG_KEY_AGREEMENT() macro.

Figure 11 Combined key agreement algorithm encoding

The underlying standalone 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.

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.

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.

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
XChaCha20	0	3	1	PSA_KEY_TYPE_XCHACHA20	0x2007
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.

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.

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.

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

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

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

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.