9.2 Key types

9.2.1 Key type encoding

psa_key_type_t (typedef)

Encoding of a key type.

typedef uint16_t psa_key_type_t;

This is a structured bitfield that identifies the category and type of key. The range of key type values is divided as follows:

PSA_KEY_TYPE_NONE == 0

Reserved as an invalid key type.

0x0001 - 0x7fff

Specification-defined key types. Key types defined by this standard always have bit 15 clear. Unallocated key type values in this range are reserved for future use.

0x8000 - 0xffff

Implementation-defined key types. Implementations that define additional key types must use an encoding with bit 15 set. The related support macros will be easier to write if these key encodings also respect the bitwise structure used by standard encodings.

The Algorithm and key type encoding appendix provides a full definition of the key type encoding.

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.

9.2.2 Key categories

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: a 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: a value of type psa_key_type_t.

Description

See Asymmetric 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: a 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: a value of type psa_key_type_t.

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

The bit size of a raw key must be a non-zero multiple of 8. The maximum size of a raw key is IMPLEMENTATION DEFINED.

Compatible algorithms

A key of this type can also be used as a non-secret input to the following key-derivation algorithms:

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_HMAC (macro)

HMAC key.

#define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100)

HMAC keys can be used in HMAC, or HMAC-based, algorithms. Although HMAC is parameterized by a specific hash algorithm, for example SHA-256, the hash algorithm is not specified in the key type. The permitted-algorithm policy for the key must specify a particular hash algorithm.

The bit size of an HMAC key must be a non-zero multiple of 8. An HMAC key is typically the same size as the output of the underlying hash algorithm. An HMAC key that is longer than the block size of the underlying hash algorithm will be hashed before use, see HMAC: Keyed-Hashing for Message Authentication [RFC2104] §2.

It is recommended that an application does not construct HMAC keys that are longer than the block size of the hash algorithm that will be used. It is implementation defined whether an HMAC key that is longer than the hash block size is supported.

If the application does not control the length of the data used to construct the HMAC key, it is recommended that the application hashes the key data, when it exceeds the hash block length, before constructing the HMAC key.

Note

PSA_HASH_LENGTH(alg) provides the output size of hash algorithm alg, in bytes.

PSA_HASH_BLOCK_LENGTH(alg) provides the block size of hash algorithm alg, in bytes.

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_DERIVE (macro)

A secret for key derivation.

#define PSA_KEY_TYPE_DERIVE ((psa_key_type_t)0x1200)

This key type is for high-entropy secrets only. For low-entropy secrets, PSA_KEY_TYPE_PASSWORD should be used instead.

These keys can be used in the PSA_KEY_DERIVATION_INPUT_SECRET or PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key-derivation algorithms.

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

The bit size of a secret for key derivation must be a non-zero multiple of 8. The maximum size of a secret for key derivation is IMPLEMENTATION DEFINED.

Compatible algorithms

A key of this type can be used as the secret input to the following key-derivation algorithms:

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_PASSWORD (macro)

A low-entropy secret for password hashing or key derivation.

Added in version 1.1.

#define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203)

This key type is suitable for passwords and passphrases which are typically intended to be memorizable by humans, and have a low entropy relative to their size. It can be used for randomly generated or derived keys with maximum or near-maximum entropy, but PSA_KEY_TYPE_DERIVE is more suitable for such keys. It is not suitable for passwords with extremely low entropy, such as numerical PINs.

These keys can be used in the PSA_KEY_DERIVATION_INPUT_PASSWORD input step of key-derivation algorithms. Algorithms that accept such an input were designed to accept low-entropy secret and are known as password hashing or key stretching algorithms.

These keys cannot be used in the PSA_KEY_DERIVATION_INPUT_SECRET input step of key-derivation algorithms, as the algorithms expect such an input to have high entropy.

The key policy determines which key-derivation algorithm the key can be used for, among the permissible subset defined above.

Compatible algorithms

A key of this type can be used as the password input to the following key-stretching algorithms:

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_PASSWORD_HASH (macro)

A secret value that can be used to verify a password hash.

Added in version 1.1.

#define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205)

The key policy determines which key-derivation algorithm the key can be used for, among the same permissible subset as for PSA_KEY_TYPE_PASSWORD.

Compatible algorithms

A key of this type can be used to output or verify the result of the following key-stretching algorithms:

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_PEPPER (macro)

A secret value that can be used when computing a password hash.

Added in version 1.1.

#define PSA_KEY_TYPE_PEPPER ((psa_key_type_t)0x1206)

The key policy determines which key-derivation algorithm the key can be used for, among the subset of algorithms that can use pepper.

Compatible algorithms

A key of this type can be used as the salt input to the following key-stretching algorithms:

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

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 is related to the AES algorithm variant. For algorithms except the XTS block cipher mode, the following key sizes are used:

  • AES-128 uses a 16-byte key : key_bits = 128

  • AES-192 uses a 24-byte key : key_bits = 192

  • AES-256 uses a 32-byte key : key_bits = 256

For the XTS block cipher mode (PSA_ALG_XTS), the following key sizes are used:

  • AES-128-XTS uses two 16-byte keys : key_bits = 256

  • AES-192-XTS uses two 24-byte keys : key_bits = 384

  • AES-256-XTS uses two 32-byte keys : key_bits = 512

The AES block cipher is defined in FIPS Publication 197: Advanced Encryption Standard (AES) [FIPS197].

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_ARIA (macro)

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

Added in version 1.1.

#define PSA_KEY_TYPE_ARIA ((psa_key_type_t)0x2406)

The size of the key is related to the ARIA algorithm variant. For algorithms except the XTS block cipher mode, the following key sizes are used:

  • ARIA-128 uses a 16-byte key : key_bits = 128

  • ARIA-192 uses a 24-byte key : key_bits = 192

  • ARIA-256 uses a 32-byte key : key_bits = 256

For the XTS block cipher mode (PSA_ALG_XTS), the following key sizes are used:

  • ARIA-128-XTS uses two 16-byte keys : key_bits = 256

  • ARIA-192-XTS uses two 24-byte keys : key_bits = 384

  • ARIA-256-XTS uses two 32-byte keys : key_bits = 512

The ARIA block cipher is defined in A Description of the ARIA Encryption Algorithm [RFC5794].

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

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 determines which DES algorithm is used:

  • Single DES uses an 8-byte key : key_bits = 64

  • 2-key 3DES uses a 16-byte key : key_bits = 128

  • 3-key 3DES uses a 24-byte key : key_bits = 192

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

The DES and 3DES block ciphers are defined in NIST Special Publication 800-67: Recommendation for the Triple Data Encryption Algorithm (TDEA) Block Cipher [SP800-67].

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key. The parity bits in each 64-bit DES key element must be correct.

Key derivation

A call to psa_key_derivation_output_key() will construct a single 64-bit DES key using the following process:

  1. Draw an 8-byte string.

  2. Set/clear the parity bits in each byte.

  3. If the result is a forbidden weak key, discard the result and return to step 1.

  4. Output the string.

For 2-key 3DES and 3-key 3DES, this process is repeated to derive the 2nd and 3rd keys, as required.

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)

The size of the key is related to the Camellia algorithm variant. For algorithms except the XTS block cipher mode, the following key sizes are used:

  • Camellia-128 uses a 16-byte key : key_bits = 128

  • Camellia-192 uses a 24-byte key : key_bits = 192

  • Camellia-256 uses a 32-byte key : key_bits = 256

For the XTS block cipher mode (PSA_ALG_XTS), the following key sizes are used:

  • Camellia-128-XTS uses two 16-byte keys : key_bits = 256

  • Camellia-192-XTS uses two 24-byte keys : key_bits = 384

  • Camellia-256-XTS uses two 32-byte keys : key_bits = 512

The Camellia block cipher is defined in Specification of Camellia — a 128-bit Block Cipher [NTT-CAM] and also described in A Description of the Camellia Encryption Algorithm [RFC3713].

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_SM4 (macro)

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

#define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405)

For algorithms except the XTS block cipher mode, the SM4 key size is 128 bits (16 bytes).

For the XTS block cipher mode (PSA_ALG_XTS), the SM4 key size is 256 bits (two 16-byte keys).

The SM4 block cipher is defined in GM/T 0002-2012: SM4 block cipher algorithm [CSTC0002].

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

PSA_KEY_TYPE_ARC4 (macro)

Key for the ARC4 stream cipher.

#define PSA_KEY_TYPE_ARC4 ((psa_key_type_t)0x2002)

Warning

The ARC4 cipher is weak and deprecated and is only recommended for use in legacy applications.

The ARC4 cipher supports key sizes between 40 and 2048 bits, that are multiples of 8. (5 to 256 bytes)

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

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw \(m/8\) bytes of output and use these as the key data, where \(m\) is the bit-size of the key.

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)

The ChaCha20 key size is 256 bits (32 bytes).

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw 32 bytes of output and use these as the key data.

PSA_KEY_TYPE_XCHACHA20 (macro)

Key for the XChaCha20 stream cipher or the XChaCha20-Poly1305 AEAD algorithm.

Added in version 1.2.

#define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007)

The XChaCha20 key size is 256 bits (32 bytes).

Compatible algorithms

Key format

The data format for import and export of the key is the raw bytes of the key.

Key derivation

A call to psa_key_derivation_output_key() will draw 32 bytes of output and use these as the key data.

9.2.4 Asymmetric keys

The Crypto API defines the following types of asymmetric key:

9.2.5 RSA keys

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)

The size of an RSA key is the bit size of the modulus.

Compatible algorithms

Key format

The data format for import and export of a key-pair is the non-encrypted DER encoding of the representation defined by in PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] as RSAPrivateKey, version 0.

RSAPrivateKey ::= SEQUENCE {
    version             INTEGER,  -- must be 0
    modulus             INTEGER,  -- n
    publicExponent      INTEGER,  -- e
    privateExponent     INTEGER,  -- d
    prime1              INTEGER,  -- p
    prime2              INTEGER,  -- q
    exponent1           INTEGER,  -- d mod (p-1)
    exponent2           INTEGER,  -- d mod (q-1)
    coefficient         INTEGER,  -- (inverse of q) mod p
}

Note

Although it is possible to define an RSA key pair or private key using a subset of these elements, the output from psa_export_key() for an RSA key pair must include all of these elements.

See PSA_KEY_TYPE_RSA_PUBLIC_KEY for the data format used when exporting the public key with psa_export_public_key().

Key generation

A call to psa_generate_key() will generate an RSA key-pair with the default public exponent of 65537. The modulus \(n=pq\) is a product of two probabilistic primes \(p\ \text{and}\ q\), where \(2^{r-1} \le n < 2^r\) and \(r\) is the bit size specified in the attributes.

The exponent can be explicitly specified in non-default production parameters in a call to psa_generate_key_custom(). Use the following custom production parameters:

  • The production parameters structure, custom, must have flags set to zero.

  • If custom_data_length == 0, the default exponent value 65537 is used.

  • The additional production parameter buffer custom_data is the public exponent, in little-endian byte order.

    The exponent must be an odd integer greater than 1. An implementation must support an exponent of 65537, and is recommended to support an exponent of 3, and can support other values.

    The maximum supported exponent value is implementation defined.

Key derivation

The method used by psa_key_derivation_output_key() to derive an RSA key-pair is implementation defined.

PSA_KEY_TYPE_RSA_PUBLIC_KEY (macro)

RSA public key.

#define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001)

The size of an RSA key is the bit size of the modulus.

Compatible algorithms

Key format

The data format for import and export of a public key is the DER encoding of the representation defined by Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [RFC3279] §2.3.1 as RSAPublicKey.

RSAPublicKey ::= SEQUENCE {
    modulus            INTEGER,    -- n
    publicExponent     INTEGER  }  -- e

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: a value of type psa_key_type_t.

9.2.6 Elliptic Curve keys

Elliptic curve keys are grouped into families of related curves. A keys for a specific curve is specified by a combination of the elliptic curve family and the bit-size of the key.

There are three categories of elliptic curve key, shown in Table 5. The curve type affects the key format, the key-derivation procedure, and the algorithms which the key can be used with.

Table 5 Types of elliptic curve key

Curve type

Curve families

Weierstrass

PSA_ECC_FAMILY_SECP_K1

PSA_ECC_FAMILY_SECP_R1

PSA_ECC_FAMILY_SECP_R2

PSA_ECC_FAMILY_SECT_K1

PSA_ECC_FAMILY_SECT_R1

PSA_ECC_FAMILY_SECT_R2

PSA_ECC_FAMILY_BRAINPOOL_P_R1

PSA_ECC_FAMILY_FRP

Montgomery

PSA_ECC_FAMILY_MONTGOMERY

Twisted Edwards

PSA_ECC_FAMILY_TWISTED_EDWARDS

psa_ecc_family_t (typedef)

The type of identifiers of an elliptic curve family.

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

Reserved. Not allocated to an ECC family.

0x01 - 0x7f

ECC family identifiers defined by this standard. Unallocated values in this range are reserved for future use.

0x80 - 0xff

Invalid. Values in this range must not be used.

The least significant bit of a elliptic curve family identifier is a parity bit for the whole key type. See Asymmetric key encoding for details of the encoding of asymmetric key types.

Implementation note

To provide other elliptic curve families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an implementation defined key type.

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.

Description

The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of \(q`\) for a curve over a field \(\mathbb{F}_q\). See the documentation of each elliptic curve family for details.

Compatible algorithms

Table 6 shows the compatible algorithms for each type of elliptic curve key-pair.

Table 6 Compatible algorithms for elliptic curve key-pairs

Curve type

Compatible algorithms

Weierstrass

Weierstrass curve key-pairs can be used in asymmetric signature, key-agreement, and key-encapsulation algorithms.

PSA_ALG_DETERMINISTIC_ECDSA

PSA_ALG_ECDSA

PSA_ALG_ECDSA_ANY

PSA_ALG_ECDH

PSA_ALG_ECIES_SEC1

Montgomery

Montgomery curve key-pairs can be used in key-agreement and key-encapsulation algorithms.

PSA_ALG_ECDH

PSA_ALG_ECIES_SEC1

Twisted Edwards

Twisted Edwards curve key-pairs can only be used in asymmetric signature algorithms.

PSA_ALG_PURE_EDDSA

PSA_ALG_ED25519PH (Edwards25519 only)

PSA_ALG_ED448PH (Edwards448 only)

Key format

The data format for import and export of the key-pair depends on the type of elliptic curve. Table 7 shows the format for each type of elliptic curve key-pair.

See PSA_KEY_TYPE_ECC_PUBLIC_KEY for the data format used when exporting the public key with psa_export_public_key().

Table 7 Key-pair formats for elliptic curve keys

Curve type

Key-pair format

Weierstrass

The key data is the content of the privateKey field of the ECPrivateKey format defined by Elliptic Curve Private Key Structure [RFC5915].

This is a \(\lceil{m/8}\rceil\)-byte string in big-endian order, where \(m\) is the key size in bits.

Montgomery

The key data is the scalar value of the ‘private key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. The value must have the forced bits set to zero or one as specified by decodeScalar25519() and decodeScalar448() in [RFC7748] §5.

This is a \(\lceil{m/8}\rceil\)-byte string where \(m\) is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.

Twisted Edwards

The key data is the private key, as defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032].

This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.

Key derivation

The key-derivation method used when calling psa_key_derivation_output_key() depends on the type of elliptic curve. Table 8 shows the derivation method for each type of elliptic curve key.

Table 8 Key derivation for elliptic curve keys

Curve type

Key derivation

Weierstrass

A Weierstrass elliptic curve private key is \(d \in [1, N - 1]\), where \(N\) is the order of the curve’s base point for ECC.

Let \(m\) be the bit size of \(N\), such that \(2^{m-1} \leq N < 2^m\). This function generates the private key using the following process:

  1. Draw a byte string of length \(\lceil{m/8}\rceil\) bytes.

  2. If \(m\) is not a multiple of 8, set the most significant \(8 * \lceil{m/8}\rceil - m`\) bits of the first byte in the string to zero.

  3. Convert the string to integer \(k\) by decoding it as a big-endian byte-string.

  4. If \(k > N-2\), discard the result and return to step 1.

  5. Output \(d = k + 1\) as the private key.

This method allows compliance to NIST standards, specifically the methods titled Key-Pair Generation by Testing Candidates in [SP800-56A] §5.6.1.2.2 or FIPS Publication 186-4: Digital Signature Standard (DSS) [FIPS186-4] §B.4.2.

Montgomery

Draw a byte string whose length is determined by the curve, and set the mandatory bits accordingly. That is:

Twisted Edwards

Draw a byte string whose length is determined by the curve, and use this as the private key. That is:

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.

Description

The size of an elliptic curve public key is the same as the corresponding private key. See PSA_KEY_TYPE_ECC_KEY_PAIR() and the documentation of each elliptic curve family for details.

Compatible algorithms

Table 9 shows the compatible algorithms for each type of elliptic curve public key.

Note

For key agreement, the public key of the peer is provided to the Crypto API as a buffer. This avoids the need to import the public-key data that is received from the peer, just to carry out the key-agreement algorithm.

Table 9 Compatible algorithms for elliptic curve public keys

Curve type

Compatible algorithms

Weierstrass

Weierstrass curve public keys can be used in asymmetric signature and key-encapsulation algorithms.

PSA_ALG_DETERMINISTIC_ECDSA

PSA_ALG_ECDSA

PSA_ALG_ECDSA_ANY

PSA_ALG_ECIES_SEC1

Montgomery

Montgomery curve public keys can only be used in key-encapsulation algorithms.

PSA_ALG_ECIES_SEC1

Twisted Edwards

Twisted Edwards curve public keys can only be used in asymmetric signature algorithms.

PSA_ALG_PURE_EDDSA

PSA_ALG_ED25519PH (Edwards25519 only)

PSA_ALG_ED448PH (Edwards448 only)

Key format

The data format for import and export of the public key depends on the type of elliptic curve. Table 10 shows the format for each type of elliptic curve public key.

Table 10 Public-key formats for elliptic curve keys

Curve type

Public-key format

Weierstrass

The key data is the uncompressed representation of an elliptic curve point as an octet string defined in SEC 1: Elliptic Curve Cryptography [SEC1] §2.3.3. If \(m\) is the bit size associated with the curve, i.e. the bit size of \(q\) for a curve over \(\mathbb{F}_q\), then the representation of point \(P\) consists of:

  • The byte 0x04;

  • \(x_P\) as a \(\lceil{m/8}\rceil\)-byte string, big-endian;

  • \(y_P\) as a \(\lceil{m/8}\rceil\)-byte string, big-endian.

Montgomery

The key data is the scalar value of the ‘public key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. This is a \(\lceil{m/8}\rceil\)-byte string where \(m\) is the key size in bits.

  • This is 32 bytes for Curve25519, computed as X25519(private_key, 9).

  • This is 56 bytes for Curve448, computed as X448(private_key, 5).

Twisted Edwards

The key data is the public key, as defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032].

This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.

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 SEC 2: Recommended Elliptic Curve Domain Parameters [SEC2].

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 = 521

They are defined in [SEC2].

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 [SEC2v1].

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 [SEC2].

Warning

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

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 [SEC2].

Warning

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

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 [SEC2].

Warning

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

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 Elliptic Curve Cryptography (ECC) Brainpool Standard Curves and Curve Generation [RFC5639].

Warning

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

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 Publication d'un paramétrage de courbe elliptique visant des applications de passeport électronique et de l'administration électronique française [FRP].

PSA_ECC_FAMILY_MONTGOMERY (macro)

Montgomery curves.

#define PSA_ECC_FAMILY_MONTGOMERY ((psa_ecc_family_t) 0x41)

This family comprises the following Montgomery curves:

  • Curve25519 : key_bits = 255

  • Curve448 : key_bits = 448

Curve25519 is defined in Curve25519: new Diffie-Hellman speed records [Curve25519]. Curve448 is defined in Ed448-Goldilocks, a new elliptic curve [Curve448].

PSA_ECC_FAMILY_TWISTED_EDWARDS (macro)

Twisted Edwards curves.

Added in version 1.1.

#define PSA_ECC_FAMILY_TWISTED_EDWARDS ((psa_ecc_family_t) 0x42)

This family comprises the following twisted Edwards curves:

  • Edwards25519 : key_bits = 255. This curve is birationally equivalent to Curve25519.

  • Edwards448 : key_bits = 448. This curve is birationally equivalent to Curve448.

Edwards25519 is defined in Twisted Edwards curves [Ed25519]. Edwards448 is defined in Ed448-Goldilocks, a new elliptic curve [Curve448].

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

9.2.7 Diffie Hellman keys

psa_dh_family_t (typedef)

The type of identifiers of a finite-field Diffie-Hellman group family.

typedef uint8_t psa_dh_family_t;

The group family identifier is required to create a finite-field 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

Reserved. Not allocated to a DH group family.

0x01 - 0x7f

DH group family identifiers defined by this standard. Unallocated values in this range are reserved for future use.

0x80 - 0xff

Invalid. Values in this range must not be used.

The least significant bit of a Diffie-Hellman group family identifier is a parity bit for the whole key type. See Asymmetric key encoding for details of the encoding of asymmetric key types.

Implementation note

To provide other Diffie-Hellman group families, it is recommended that an implementation defines a key type with bit 15 set, which indicates an implementation defined key type.

PSA_KEY_TYPE_DH_KEY_PAIR (macro)

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

Compatible algorithms

Key format

The data format for import and export of the key pair is the representation of the private key \(x\) as a big-endian byte string. The length of the byte string is the private key’s size in bytes, and leading zeroes are not stripped.

See PSA_KEY_TYPE_DH_PUBLIC_KEY for the data format used when exporting the public key with psa_export_public_key().

Key derivation

A call to psa_key_derivation_output_key() will use the following process, defined in Key-Pair Generation by Testing Candidates in NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography [SP800-56A] §5.6.1.1.4.

A Diffie-Hellman private key is \(x \in [1, p - 1]\), where \(p\) is the group’s prime modulus. Let \(m\) be the bit size of \(p\), such that \(2^{m-1} \leq p < 2^m\).

This function generates the private key using the following process:

  1. Draw a byte string of length \(\lceil{m/8}\rceil\) bytes.

  2. If \(m\) is not a multiple of 8, set the most significant \(8 * \lceil{m/8}\rceil - m`\) bits of the first byte in the string to zero.

  3. Convert the string to integer \(k\) by decoding it as a big-endian byte-string.

  4. If \(k > p-2\), discard the result and return to step 1.

  5. Output \(x = k + 1\) as the private key.

PSA_KEY_TYPE_DH_PUBLIC_KEY (macro)

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

Compatible algorithms

None: Finite-field Diffie-Hellman public keys are exported to use in a key-agreement algorithm, and the peer key is provided to the PSA_ALG_FFDH key-agreement algorithm as a buffer of key data.

Key format

The data format for export of the public key is the representation of the public key \(y = g^x\!\mod p\) as a big-endian byte string. The length of the byte string is the length of the base prime \(p\) in bytes.

PSA_DH_FAMILY_RFC7919 (macro)

Finite-field Diffie-Hellman groups defined for TLS in RFC 7919.

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

Keys is this group can only be used with the PSA_ALG_FFDH key-agreement algorithm.

These groups are defined by Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security (TLS) [RFC7919] Appendix A.

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

9.2.8 SPAKE2+ keys

PSA_KEY_TYPE_SPAKE2P_KEY_PAIR (macro)

SPAKE2+ key pair: both the prover and verifier key.

Added in version 1.2.

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

Parameters

curve

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

Description

The bit-size of a SPAKE2+ key is the size associated with the elliptic curve group, that is, \(\lceil{log_2(q)}\rceil\) for a curve over a field \(\mathbb{F}_q\). See Elliptic Curve keys for details of each elliptic curve family.

To create a new SPAKE2+ key pair, use psa_key_derivation_output_key() as described in SPAKE2+ registration. The SPAKE2+ protocol recommends that a key-stretching key-derivation function, such as PBKDF2, is used to hash the SPAKE2+ password. This follows the recommended process described in [RFC9383].

A SPAKE2+ key pair can also be imported from a previously exported SPAKE2+ key pair.

The corresponding public key can be exported using psa_export_public_key(). See also PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY().

Compatible algorithms

Key format

A SPAKE2+ key pair consists of the two values \(w0\) and \(w1\), which result from the SPAKE2+ registration phase, see SPAKE2+ registration. \(w0\) and \(w1\) are scalars in the same range as an elliptic curve private key from the group used as the SPAKE2+ primitive group.

The data format for import and export of the key pair is the concatenation of the formatted values for \(w0\) and \(w1\), using the standard formats for elliptic curve keys used by the Crypto API. For example, for SPAKE2+ over P-256 (secp256r1), the output from psa_export_key() would be the concatenation of:

  • The P-256 private key \(w0\). This is a 32-byte big-endian encoding of the integer \(w0\).

  • The P-256 private key \(w1\). This is a 32-byte big-endian encoding of the integer \(w1\).

See PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY for the data format used when exporting the public key with psa_export_public_key().

Key derivation

A call to psa_key_derivation_output_key() will use the following process, which follows the recommendations for the registration process in SPAKE2+, an Augmented Password-Authenticated Key Exchange (PAKE) Protocol [RFC9383], and matches the specification of this process in Matter Specification, Version 1.2 [MATTER].

The derivation of SPAKE2+ keys extracts \(\lceil{log_2(p)/8}\rceil+8\) bytes from the PBKDF for each of \(w0s\) and \(w1s\), where \(p\) is the prime factor of the order of the elliptic curve group. The following sizes are used for extracting \(w0s\) and \(w1s\), depending on the elliptic curve:

  • P-256: 40 bytes

  • P-384: 56 bytes

  • P-521: 74 bytes

  • edwards25519: 40 bytes

  • edwards448: 64 bytes

The calculation of \(w0\), \(w1\), and \(L\) then proceeds as described in [RFC9383].

Implementation note

The values of \(w0\) and \(w1\) are required as part of the SPAKE2+ key pair.

It is implementation defined whether \(L\) is computed during key derivation, and stored as part of the key pair; or only computed when required from the key pair.

PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY (macro)

SPAKE2+ public key: the verifier key.

Added in version 1.2.

#define PSA_KEY_TYPE_SPAKE2P_PUBLIC_KEY(curve) \
    /* specification-defined value */

Parameters

curve

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

Description

The bit-size of an SPAKE2+ public key is the same as the corresponding private key. See PSA_KEY_TYPE_SPAKE2P_KEY_PAIR() and the documentation of each elliptic curve family for details.

To construct a SPAKE2+ public key, it must be imported.

Compatible algorithms

Key format

A SPAKE2+ public key consists of the two values \(w0\) and \(L\), which result from the SPAKE2+ registration phase, see SPAKE2+ registration. \(w0\) is a scalar in the same range as a elliptic curve private key from the group used as the SPAKE2+ primitive group. \(L\) is a point on the curve, similar to a public key from the same group, corresponding to the \(w1\) value in the key pair.

The data format for import and export of the public key is the concatenation of the formatted values for \(w0\) and \(L\), using the standard formats for elliptic curve keys used by the Crypto API. For example, for SPAKE2+ over P-256 (secp256r1), the output from psa_export_public_key() would be the concatenation of:

  • The P-256 private key \(w0\). This is a 32-byte big-endian encoding of the integer \(w0\).

  • The P-256 public key \(L\). This is a 65-byte concatenation of:

    • The byte 0x04.

    • The 32-byte big-endian encoding of the x-coordinate of \(L\).

    • The 32-byte big-endian encoding of the y-coordinate of \(L\).

PSA_KEY_TYPE_IS_SPAKE2P (macro)

Whether a key type is a SPAKE2+ key, either a key pair or a public key.

Added in version 1.2.

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

Parameters

type

A key type: a value of type psa_key_type_t.

PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR (macro)

Whether a key type is a SPAKE2+ key pair.

Added in version 1.2.

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

Parameters

type

A key type: a value of type psa_key_type_t.

PSA_KEY_TYPE_IS_SPAKE2P_PUBLIC_KEY (macro)

Whether a key type is a SPAKE2+ public key.

Added in version 1.2.

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

Parameters

type

A key type: a value of type psa_key_type_t.

PSA_KEY_TYPE_SPAKE2P_GET_FAMILY (macro)

Extract the curve family from a SPAKE2+ key type.

Added in version 1.2.

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

Parameters

type

A SPAKE2+ key type: a value of type psa_key_type_t such that PSA_KEY_TYPE_IS_SPAKE2P(type) is true.

Returns: psa_ecc_family_t

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

9.2.9 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. It can be efficiently implemented as a static inline function or a function-like-macro.

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. It can be efficiently implemented as a static inline function or a function-like-macro.

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. It can be efficiently implemented as a static inline function or a function-like-macro.

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. It can be efficiently implemented as a static inline function or a function-like-macro.