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.

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

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.

../_images/mac.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

  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.

../_images/cipher.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

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.

../_images/aead.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

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.

../_images/kdf.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)

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.

../_images/sign.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

  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.

../_images/pke.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

  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.

../_images/ka_raw.svg

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.

../_images/ka_combined.svg

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.

../_images/key_type.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.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.svg

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

../_images/asymmetric_key.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.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.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

  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.

../_images/dh_key.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

  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.