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

Figure 6 Encoding of psa_algorithm_t

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

Table 14 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 15.

Table 15 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
Key encapsulation	0x0C	See Key-encapsulation algorithm encoding
PAKE	0x0A	See PAKE algorithm encoding

B.1.2 Hash algorithm encoding

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

Figure 7 Hash algorithm encoding

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

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

Figure 8 MAC algorithm encoding

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

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

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

Figure 9 CIPHER algorithm encoding

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

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

Figure 10 AEAD algorithm encoding

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

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

Figure 11 Key-derivation algorithm encoding

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

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

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

Figure 12 Asymmetric signature algorithm encoding

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

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

Table 21 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 13.

Figure 13 Asymmetric encryption algorithm encoding

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

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

Table 22 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 14.

Figure 14 Standalone key-agreement algorithm encoding

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

Table 23 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 15 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.1.10 Key-encapsulation algorithm encoding

The algorithm identifier for key-encapsulation algorithms defined in this specification are encoded as shown in Figure 16.

Figure 16 Encapsulation algorithm encoding

The defined values for ENCAPS-TYPE are shown in Table 24.

Table 24 Encapsulation algorithm sub-type values

Encapsulation algorithm	ENCAPS-TYPE	Algorithm identifier	Algorithm value
ECIES (SEC1)	0x01	PSA_ALG_ECIES_SEC1	0x0C000100

B.1.11 PAKE algorithm encoding

The algorithm identifier for PAKE algorithms defined in this specification are encoded as shown in Figure 17.

Figure 17 PAKE algorithm encoding

The defined values for PAKE-TYPE are shown in Table 25.

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

Table 25 PAKE algorithm sub-type values

PAKE algorithm	PAKE-TYPE	Algorithm identifier	Algorithm value
J-PAKE	0x01	PSA_ALG_JPAKE(hash)	0x0A0001hh a
SPAKE2+ with HMAC	0x04	PSA_ALG_SPAKE2P_HMAC(hash)	0x0A0004hh a
SPAKE2+ with CMAC	0x05	PSA_ALG_SPAKE2P_CMAC(hash)	0x0A0005hh a
SPAKE2+ for Matter	0x06	PSA_ALG_SPAKE2P_MATTER	0x0A000609

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

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

Figure 18 Encoding of psa_key_type_t

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

Table 26 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 27.

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

Figure 19 Raw key encoding

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

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

Figure 20 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 29.

Table 29 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 21.

Figure 21 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 30.

The defined values for FAMILY depend on the ASYM-TYPE value. See the details for each asymmetric key sub-type.

Table 30 Asymmetric key sub-type values

Asymmetric key type	ASYM-TYPE	Details
Non-parameterized	0	See Non-parameterized asymmetric key encoding
Elliptic Curve	2	See Elliptic curve key encoding
Diffie-Hellman	4	See Diffie Hellman key encoding
SPAKE2+	8	See SPAKE2+ key encoding

Non-parameterized asymmetric key encoding

The key type for non-parameterized asymmetric keys defined in this specification are encoded as shown in Figure 22.

Figure 22 Non-parameterized asymmetric keys encoding

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

The defined values for NP-FAMILY and P are shown in Table 31.

Table 31 Non-parameterized asymmetric key family values

Key family	Public/pair	PAIR	NP-FAMILY	P	Key type	Key value
RSA	Public key	0	0	1	PSA_KEY_TYPE_RSA_PUBLIC_KEY	0x4001
	Key pair	3	0	1	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 23.

Figure 23 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 32.

Table 32 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 elliptic curve family values defined in the API also include the parity bit. 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 24.

Figure 24 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 33.

Table 33 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 Diffie Hellman family values defined in the API also include the parity bit. 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.

SPAKE2+ key encoding

The key type for SPAKE2+ keys defined in this specification are encoded as shown in Figure 25.

Figure 25 SPAKE2+ 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 34.

Table 34 SPAKE2+ key family values

SPAKE2+ group	ECC-FAMILY	P	ECC family a	Public-key value	Key-pair value
SECP R1	0x09	0	PSA_ECC_FAMILY_SECP_R1	0x4412	0x7412
Twisted Edwards	0x21	0	PSA_ECC_FAMILY_TWISTED_EDWARDS	0x4442	0x7442

1. The elliptic curve family values defined in the API also include the parity bit. The key type value is constructed from the elliptic curve family using either PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(family) or PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(family) as required.