Key types

Key categories

PSA_KEY_TYPE_NONE (macro)

An invalid key type value.

#define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000)

Zero is not the encoding of any key type.

PSA_KEY_TYPE_IS_UNSTRUCTURED (macro)

Whether a key type is an unstructured array of bytes.

#define PSA_KEY_TYPE_IS_UNSTRUCTURED(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

Description

This encompasses both symmetric keys and non-key data.

See Symmetric keys for a list of symmetric key types.

PSA_KEY_TYPE_IS_ASYMMETRIC (macro)

Whether a key type is asymmetric: either a key pair or a public key.

#define PSA_KEY_TYPE_IS_ASYMMETRIC(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

Description

See RSA keys for a list of asymmetric key types.

PSA_KEY_TYPE_IS_PUBLIC_KEY (macro)

Whether a key type is the public part of a key pair.

#define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_IS_KEY_PAIR (macro)

Whether a key type is a key pair containing a private part and a public part.

#define PSA_KEY_TYPE_IS_KEY_PAIR(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

Symmetric keys

PSA_KEY_TYPE_RAW_DATA (macro)

Raw data.

#define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x1001)

A “key” of this type cannot be used for any cryptographic operation. Applications can use this type to store arbitrary data in the keystore.

PSA_KEY_TYPE_HMAC (macro)

HMAC key.

#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100)

The key policy determines which underlying hash algorithm the key can be used for.

HMAC keys typically have the same size as the underlying hash. This size can be calculated with PSA_HASH_LENGTH(alg) where alg is the HMAC algorithm or the underlying hash algorithm.

PSA_KEY_TYPE_DERIVE (macro)

A secret for key derivation.

#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200)

The key policy determines which key derivation algorithm the key can be used for.

PSA_KEY_TYPE_AES (macro)

Key for a cipher, AEAD or MAC algorithm based on the AES block cipher.

#define PSA_KEY_TYPE_AES ((psa_key_type_t)0x2400)

The size of the key can be 16 bytes (AES-128), 24 bytes (AES-192) or 32 bytes (AES-256).

PSA_KEY_TYPE_DES (macro)

Key for a cipher or MAC algorithm based on DES or 3DES (Triple-DES).

#define PSA_KEY_TYPE_DES ((psa_key_type_t)0x2301)

The size of the key can be 8 bytes (single DES), 16 bytes (2-key 3DES) or 24 bytes (3-key 3DES).

Warning

Single DES and 2-key 3DES are weak and strongly deprecated and are only recommended for decrypting legacy data.

3-key 3DES is weak and deprecated and is only recommended for use in legacy protocols.

PSA_KEY_TYPE_CAMELLIA (macro)

Key for a cipher, AEAD or MAC algorithm based on the Camellia block cipher.

#define PSA_KEY_TYPE_CAMELLIA ((psa_key_type_t)0x2403)

PSA_KEY_TYPE_ARC4 (macro)

Key for the RC4 stream cipher.

#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002)

Use algorithm PSA_ALG_STREAM_CIPHER to use this key with the ARC4 cipher.

Warning

The RC4 cipher is weak and deprecated and is only recommended for use in legacy protocols.

The ARC4 cipher does not use an initialization vector (IV). When using a multi-part cipher operation with the PSA_ALG_STREAM_CIPHER algorithm and an ARC4 key, psa_cipher_generate_iv() and psa_cipher_set_iv() must not be called.

PSA_KEY_TYPE_CHACHA20 (macro)

Key for the ChaCha20 stream cipher or the Chacha20-Poly1305 AEAD algorithm.

#define PSA_KEY_TYPE_CHACHA20 ((psa_key_type_t)0x2004)

ChaCha20 and the ChaCha20_Poly1305 construction are defined in RFC 7539.

Variants of these algorithms are defined by the length of the nonce:

  • Implementations must support a 12-byte nonce, as defined in RFC 7539.
  • Implementations can optionally support an 8-byte nonce, the original variant.
  • It is recommended that implementations do not support other sizes of nonce.

Use algorithm PSA_ALG_STREAM_CIPHER to use this key with the ChaCha20 cipher for unauthenticated encryption.

RSA keys

PSA_KEY_TYPE_RSA_PUBLIC_KEY (macro)

RSA public key.

#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001)

PSA_KEY_TYPE_RSA_KEY_PAIR (macro)

RSA key pair: both the private and public key.

#define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001)

PSA_KEY_TYPE_IS_RSA (macro)

Whether a key type is an RSA key. This includes both key pairs and public keys.

#define PSA_KEY_TYPE_IS_RSA(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

Elliptic Curve keys

psa_ecc_family_t (type)

The type of PSA elliptic curve family identifiers.

typedef uint8_t psa_ecc_family_t;

The curve identifier is required to create an ECC key using the PSA_KEY_TYPE_ECC_KEY_PAIR() or PSA_KEY_TYPE_ECC_PUBLIC_KEY() macros.

The specific ECC curve within a family is identified by the key_bits attribute of the key.

The range of Elliptic curve family identifier values is divided as follows:

0x00 - 0x7f
ECC family identifiers defined by this standard. Unallocated values in this range are reserved for future use.
0x80 - 0xff
Implementations that define additional families must use an encoding in this range.

PSA_KEY_TYPE_ECC_KEY_PAIR (macro)

Elliptic curve key pair: both the private and public key.

#define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) /* specification-defined value */

Parameters

curve
A value of type psa_ecc_family_t that identifies the ECC curve family to be used.

PSA_KEY_TYPE_ECC_PUBLIC_KEY (macro)

Elliptic curve public key.

#define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) /* specification-defined value */

Parameters

curve
A value of type psa_ecc_family_t that identifies the ECC curve family to be used.

PSA_ECC_FAMILY_SECP_K1 (macro)

SEC Koblitz curves over prime fields.

#define PSA_ECC_FAMILY_SECP_K1 ((psa_ecc_family_t) 0x17)

This family comprises the following curves:

  • secp192k1 : key_bits = 192
  • secp224k1 : key_bits = 225
  • secp256k1 : key_bits = 256

They are defined in Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters.

PSA_ECC_FAMILY_SECP_R1 (macro)

SEC random curves over prime fields.

#define PSA_ECC_FAMILY_SECP_R1 ((psa_ecc_family_t) 0x12)

This family comprises the following curves:

  • secp192r1 : key_bits = 192
  • secp224r1 : key_bits = 224
  • secp256r1 : key_bits = 256
  • secp384r1 : key_bits = 384
  • secp521r1 : key_bits = 512

They are defined in Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters

PSA_ECC_FAMILY_SECP_R2 (macro)

Warning

This family of curves is weak and deprecated.

#define PSA_ECC_FAMILY_SECP_R2 ((psa_ecc_family_t) 0x1b)

This family comprises the following curves:

  • secp160r2 : key_bits = 160 (Deprecated)

It is defined in the superseded SEC 2: Recommended Elliptic Curve Domain Parameters, Version 1.0.

PSA_ECC_FAMILY_SECT_K1 (macro)

SEC Koblitz curves over binary fields.

#define PSA_ECC_FAMILY_SECT_K1 ((psa_ecc_family_t) 0x27)

This family comprises the following curves:

  • sect163k1 : key_bits = 163 (Deprecated)
  • sect233k1 : key_bits = 233
  • sect239k1 : key_bits = 239
  • sect283k1 : key_bits = 283
  • sect409k1 : key_bits = 409
  • sect571k1 : key_bits = 571

They are defined in Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters

Warning

The 163-bit curve sect163k1 is weak and deprecated and is only recommended for use in legacy protocols.

PSA_ECC_FAMILY_SECT_R1 (macro)

SEC random curves over binary fields.

#define PSA_ECC_FAMILY_SECT_R1 ((psa_ecc_family_t) 0x22)

This family comprises the following curves:

  • sect163r1 : key_bits = 163 (Deprecated)
  • sect233r1 : key_bits = 233
  • sect283r1 : key_bits = 283
  • sect409r1 : key_bits = 409
  • sect571r1 : key_bits = 571

They are defined in Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters

Warning

The 163-bit curve sect163r1 is weak and deprecated and is only recommended for use in legacy protocols.

PSA_ECC_FAMILY_SECT_R2 (macro)

SEC additional random curves over binary fields.

#define PSA_ECC_FAMILY_SECT_R2 ((psa_ecc_family_t) 0x2b)

This family comprises the following curves:

  • sect163r2 : key_bits = 163 (Deprecated)

It is defined in Standards for Efficient Cryptography, SEC 2: Recommended Elliptic Curve Domain Parameters

Warning

The 163-bit curve sect163r2 is weak and deprecated and is only recommended for use in legacy protocols.

PSA_ECC_FAMILY_BRAINPOOL_P_R1 (macro)

Brainpool P random curves.

#define PSA_ECC_FAMILY_BRAINPOOL_P_R1 ((psa_ecc_family_t) 0x30)

This family comprises the following curves:

  • brainpoolP160r1 : key_bits = 160 (Deprecated)
  • brainpoolP192r1 : key_bits = 192
  • brainpoolP224r1 : key_bits = 224
  • brainpoolP256r1 : key_bits = 256
  • brainpoolP320r1 : key_bits = 320
  • brainpoolP384r1 : key_bits = 384
  • brainpoolP512r1 : key_bits = 512

They are defined in RFC 5639.

Warning

The 160-bit curve brainpoolP160r1 is weak and deprecated and is only recommended for use in legacy protocols.

PSA_ECC_FAMILY_FRP (macro)

Curve used primarily in France and elsewhere in Europe.

#define PSA_ECC_FAMILY_FRP ((psa_ecc_family_t) 0x33)

This family comprises one 256-bit curve:

  • FRP256v1 : key_bits = 256

This is defined by Agence nationale de la sécurité des systèmes d’information in Publication d’un paramétrage de courbe elliptique visant des applications de passeport électronique et de l’administration électronique française, 21 November 2011.

PSA_ECC_FAMILY_MONTGOMERY (macro)

Montgomery curves.

#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t) 0x41)

This family comprises the following Montgomery curves:

PSA_KEY_TYPE_IS_ECC (macro)

Whether a key type is an elliptic curve key, either a key pair or a public key.

#define PSA_KEY_TYPE_IS_ECC(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_IS_ECC_KEY_PAIR (macro)

Whether a key type is an elliptic curve key pair.

#define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY (macro)

Whether a key type is an elliptic curve public key.

#define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_ECC_GET_FAMILY (macro)

Extract the curve family from an elliptic curve key type.

#define PSA_KEY_TYPE_ECC_GET_FAMILY(type) /* specification-defined value */

Parameters

type
An elliptic curve key type (value of type psa_key_type_t such that PSA_KEY_TYPE_IS_ECC(type) is true).

Returns: psa_ecc_family_t

The elliptic curve family id, if type is a supported elliptic curve key. Unspecified if type is not a supported elliptic curve key.

Diffie Hellman keys

psa_dh_family_t (type)

The type of PSA Diffie-Hellman group family identifiers.

typedef uint8_t psa_dh_family_t;

The group family identifier is required to create an Diffie-Hellman key using the PSA_KEY_TYPE_DH_KEY_PAIR() or PSA_KEY_TYPE_DH_PUBLIC_KEY() macros.

The specific Diffie-Hellman group within a family is identified by the key_bits attribute of the key.

The range of Diffie-Hellman group family identifier values is divided as follows:

0x00 - 0x7f
DH group family identifiers defined by this standard. Unallocated values in this range are reserved for future use.
0x80 - 0xff
Implementations that define additional families must use an encoding in this range.

PSA_KEY_TYPE_DH_KEY_PAIR (macro)

Diffie-Hellman key pair: both the private key and public key.

#define PSA_KEY_TYPE_DH_KEY_PAIR(group) /* specification-defined value */

Parameters

group
A value of type psa_dh_family_t that identifies the Diffie-Hellman group family to be used.

PSA_KEY_TYPE_DH_PUBLIC_KEY (macro)

Diffie-Hellman public key.

#define PSA_KEY_TYPE_DH_PUBLIC_KEY(group) /* specification-defined value */

Parameters

group
A value of type psa_dh_family_t that identifies the Diffie-Hellman group family to be used.

PSA_DH_FAMILY_RFC7919 (macro)

Diffie-Hellman groups defined in RFC 7919 Appendix A.

#define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03)

This family includes groups with the following key sizes (in bits): 2048, 3072, 4096, 6144, 8192. An implementation can support all of these sizes or only a subset.

PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY (macro)

The key pair type corresponding to a public key type.

#define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \
    /* specification-defined value */

Parameters

type
A public key type or key pair type.

Returns

The corresponding key pair type. If type is not a public key or a key pair, the return value is undefined.

Description

If type is a key pair type, it will be left unchanged.

PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR (macro)

The public key type corresponding to a key pair type.

#define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \
    /* specification-defined value */

Parameters

type
A public key type or key pair type.

Returns

The corresponding public key type. If type is not a public key or a key pair, the return value is undefined.

Description

If type is a public key type, it will be left unchanged.

PSA_KEY_TYPE_IS_DH (macro)

Whether a key type is a Diffie-Hellman key, either a key pair or a public key.

#define PSA_KEY_TYPE_IS_DH(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_IS_DH_KEY_PAIR (macro)

Whether a key type is a Diffie-Hellman key pair.

#define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_IS_DH_PUBLIC_KEY (macro)

Whether a key type is a Diffie-Hellman public key.

#define PSA_KEY_TYPE_IS_DH_PUBLIC_KEY(type) /* specification-defined value */

Parameters

type
A key type (value of type psa_key_type_t).

PSA_KEY_TYPE_DH_GET_FAMILY (macro)

Extract the group family from a Diffie-Hellman key type.

#define PSA_KEY_TYPE_DH_GET_FAMILY(type) /* specification-defined value */

Parameters

type
A Diffie-Hellman key type (value of type psa_key_type_t such that PSA_KEY_TYPE_IS_DH(type) is true).

Returns: psa_dh_family_t

The Diffie-Hellman group family id, if type is a supported Diffie-Hellman key. Unspecified if type is not a supported Diffie-Hellman key.

Attribute accessors

psa_set_key_type (function)

Declare the type of a key.

void psa_set_key_type(psa_key_attributes_t * attributes,
                      psa_key_type_t type);

Parameters

attributes
The attribute object to write to.
type
The key type to write. If this is PSA_KEY_TYPE_NONE, the key type in attributes becomes unspecified.

Returns: void

Description

This function overwrites any key type previously set in attributes.

Implementation note

This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:

  • This function can be declared as static or inline, instead of using the default external linkage.
  • This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.

psa_get_key_type (function)

Retrieve the key type from key attributes.

psa_key_type_t psa_get_key_type(const psa_key_attributes_t * attributes);

Parameters

attributes
The key attribute object to query.

Returns: psa_key_type_t

The key type stored in the attribute object.

Description

Implementation note

This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:

  • This function can be declared as static or inline, instead of using the default external linkage.
  • This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.

psa_get_key_bits (function)

Retrieve the key size from key attributes.

size_t psa_get_key_bits(const psa_key_attributes_t * attributes);

Parameters

attributes
The key attribute object to query.

Returns: size_t

The key size stored in the attribute object, in bits.

Description

Implementation note

This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:

  • This function can be declared as static or inline, instead of using the default external linkage.
  • This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.

psa_set_key_bits (function)

Declare the size of a key.

void psa_set_key_bits(psa_key_attributes_t * attributes,
                      size_t bits);

Parameters

attributes
The attribute object to write to.
bits
The key size in bits. If this is 0, the key size in attributes becomes unspecified. Keys of size 0 are not supported.

Returns: void

Description

This function overwrites any key size previously set in attributes.

Implementation note

This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:

  • This function can be declared as static or inline, instead of using the default external linkage.
  • This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.