diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 8cc8cf5c..545377ad 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -24,6 +24,7 @@ typedef uint32_t psa_pake_primitive_t; typedef uint8_t psa_pake_primitive_type_t; typedef uint8_t psa_pake_role_t; typedef uint8_t psa_pake_step_t; +typedef uint8_t psa_slh_dsa_family_t; typedef struct psa_custom_key_parameters_t { uint32_t flags; } psa_custom_key_parameters_t; @@ -72,6 +73,9 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_CMAC ((psa_algorithm_t)0x03c00200) #define PSA_ALG_CTR ((psa_algorithm_t)0x04c01000) #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) /* specification-defined value */ +#define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash_alg) \ + /* specification-defined value */ +#define PSA_ALG_DETERMINISTIC_SLH_DSA ((psa_algorithm_t) 0x06004100) #define PSA_ALG_ECB_NO_PADDING ((psa_algorithm_t)0x04404400) #define PSA_ALG_ECDH ((psa_algorithm_t)0x09020000) #define PSA_ALG_ECDSA(hash_alg) /* specification-defined value */ @@ -82,6 +86,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_FULL_LENGTH_MAC(mac_alg) /* specification-defined value */ #define PSA_ALG_GCM ((psa_algorithm_t)0x05500200) #define PSA_ALG_GET_HASH(alg) /* specification-defined value */ +#define PSA_ALG_HASH_SLH_DSA(hash_alg) /* specification-defined value */ #define PSA_ALG_HKDF(hash_alg) /* specification-defined value */ #define PSA_ALG_HKDF_EXPAND(hash_alg) /* specification-defined value */ #define PSA_ALG_HKDF_EXTRACT(hash_alg) /* specification-defined value */ @@ -92,12 +97,16 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) /* specification-defined value */ #define PSA_ALG_IS_CIPHER(alg) /* specification-defined value */ #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \ + /* specification-defined value */ #define PSA_ALG_IS_ECDH(alg) /* specification-defined value */ #define PSA_ALG_IS_ECDSA(alg) /* specification-defined value */ #define PSA_ALG_IS_FFDH(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH_AND_SIGN(alg) /* specification-defined value */ #define PSA_ALG_IS_HASH_EDDSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HASH_SLH_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) /* specification-defined value */ #define PSA_ALG_IS_HKDF(alg) /* specification-defined value */ #define PSA_ALG_IS_HKDF_EXPAND(alg) /* specification-defined value */ #define PSA_ALG_IS_HKDF_EXTRACT(alg) /* specification-defined value */ @@ -121,6 +130,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_SIGN(alg) /* specification-defined value */ #define PSA_ALG_IS_SIGN_HASH(alg) /* specification-defined value */ #define PSA_ALG_IS_SIGN_MESSAGE(alg) /* specification-defined value */ +#define PSA_ALG_IS_SLH_DSA(alg) /* specification-defined value */ #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ /* specification-defined value */ #define PSA_ALG_IS_SPAKE2P(alg) /* specification-defined value */ @@ -156,6 +166,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_SHA3_256 ((psa_algorithm_t)0x02000011) #define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012) #define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013) +#define PSA_ALG_SHAKE128_256 ((psa_algorithm_t)0x02000016) #define PSA_ALG_SHAKE256_512 ((psa_algorithm_t)0x02000015) #define PSA_ALG_SHA_1 ((psa_algorithm_t)0x02000005) #define PSA_ALG_SHA_224 ((psa_algorithm_t)0x02000008) @@ -164,6 +175,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_SHA_512 ((psa_algorithm_t)0x0200000b) #define PSA_ALG_SHA_512_224 ((psa_algorithm_t)0x0200000c) #define PSA_ALG_SHA_512_256 ((psa_algorithm_t)0x0200000d) +#define PSA_ALG_SLH_DSA ((psa_algorithm_t) 0x06004000) #define PSA_ALG_SM3 ((psa_algorithm_t)0x02000014) #define PSA_ALG_SP800_108_COUNTER_CMAC ((psa_algorithm_t)0x08000800) #define PSA_ALG_SP800_108_COUNTER_HMAC(hash_alg) \ @@ -299,6 +311,11 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_IS_KEY_PAIR(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_RSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ + /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ + /* specification-defined value */ #define PSA_KEY_TYPE_IS_SPAKE2P(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \ /* specification-defined value */ @@ -316,6 +333,9 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x1001) #define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001) #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001) +#define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) /* specification-defined value */ #define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405) #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) /* specification-defined value */ #define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) /* specification-defined value */ @@ -373,6 +393,10 @@ typedef struct psa_custom_key_parameters_t { #define PSA_SIGNATURE_MAX_SIZE /* implementation-defined value */ #define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \ /* implementation-defined value */ +#define PSA_SLH_DSA_FAMILY_SHA2_F ((psa_slh_dsa_family_t) 0x04) +#define PSA_SLH_DSA_FAMILY_SHA2_S ((psa_slh_dsa_family_t) 0x02) +#define PSA_SLH_DSA_FAMILY_SHAKE_F ((psa_slh_dsa_family_t) 0x0d) +#define PSA_SLH_DSA_FAMILY_SHAKE_S ((psa_slh_dsa_family_t) 0x0b) #define PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE 32 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */ psa_status_t psa_aead_abort(psa_aead_operation_t * operation); diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index ea18391c..ea11c788 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -592,9 +592,38 @@ The |API| defines the following types of asymmetric key: * :secref:`rsa-keys` * :secref:`ecc-keys` +* :secref:`slh-dsa-keys` * :secref:`dh-keys` * :secref:`spake2p-keys` +.. macro:: PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + The key pair type corresponding to a public key type. + + .. param:: type + A public key type or key pair type. + + .. return:: + The corresponding key pair type. If ``type`` is not a public key or a key pair, the return value is undefined. + + If ``type`` is a key pair type, it will be left unchanged. + +.. macro:: PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + The public key type corresponding to a key pair type. + + .. param:: type + A public key type or key pair type. + + .. return:: + The corresponding public key type. If ``type`` is not a public key or a key pair, the return value is undefined. + + If ``type`` is a public key type, it will be left unchanged. + .. _rsa-keys: RSA keys @@ -781,7 +810,7 @@ The curve type affects the key format, the key derivation procedure, and the alg .. param:: curve A value of type `psa_ecc_family_t` that identifies the ECC curve family to be used. - The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q`` for a curve over a field :math:`\mathbb{F}_q`. + The size of an elliptic curve key is the bit size associated with the curve, that is, the bit size of :math:`q` for a curve over a field :math:`\mathbb{F}_q`. See the documentation of each elliptic curve family for details. .. subsection:: Compatible algorithms @@ -1165,6 +1194,223 @@ The curve type affects the key format, the key derivation procedure, and the alg .. return:: 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. +.. _slh-dsa-keys: + +Stateless Hash-based Signature keys +----------------------------------- + +The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined in :cite-title:`FIPS205`. + +.. typedef:: uint8_t psa_slh_dsa_family_t + + .. summary:: + The type of identifiers of a Stateless hash-based DSA parameter set. + + The parameter-set identifier is required to create an SLH-DSA key using the `PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` or `PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` macros. + + The specific SLH-DSA parameter set within a family is identified by the ``key_bits`` attribute of the key. + + The range of SLH-DSA family identifier values is divided as follows: + + :code:`0x00` + Reserved. + Not allocated to an SLH-DSA parameter-set family. + :code:`0x01 - 0x7f` + SLH-DSA parameter-set family identifiers defined by this standard. + Unallocated values in this range are reserved for future use. + :code:`0x80 - 0xff` + Invalid. + Values in this range must not be used. + + The least significant bit of an SLH-DSA family identifier is a parity bit for the whole key type. + See :secref:`slh-dsa-key-encoding` for details of the encoding of asymmetric key types. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + SLH-DSA key pair: both the private key and public key. + + .. param:: set + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. + + The key attribute size of of an SLH-DSA key pair is the bit-size of each component in the SLH-DSA keys defined in `[FIPS205]`. + That is, for a parameter set with security parameter :math:`n`, the bit-size in the key attributes is :math:`8n`. + See the documentation of each SLH-DSA parameter-set family for details. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_SLH_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for SHL-DSA public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-SLHDSA`. + + The current proposed format is based on the current expected outcome of that process. + + A SLH-DSA key-pair is defined in `[FIPS205]` §9.1 as the four :math:`n`\ -byte values, :math:`SK\text{.seed}`, :math:`SK\text{.prf}`, :math:`PK\text{.seed}`, and :math:`PK\text{.root}`, where :math:`n` is the security parameter. + + The data format for import and export of the key-pair is the concatenation of the four octet strings: + + .. math:: + + SK\text{.seed}\ ||\ SK\text{.prf}\ ||\ PK\text{.seed}\ ||\ PK\text{.root} + + See `PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`. + + .. subsection:: Key derivation + + A call to `psa_key_derivation_output_key()` will draw output bytes as follows: + + * 32 bytes are drawn as :math:`SK\text{.seed}`. + * 32 bytes are drawn as :math:`SK\text{.prf}`. + * 32 bytes are drawn as :math:`PK\text{.seed}`. + + The private key :math:`(SK\text{.seed},SK\text{.prf},PK\text{.seed},PK\text{.root})` is generated from these values as defined by ``slh_keygen_internal()`` in `[FIPS205]` §9.1. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + SLH-DSA public key. + + .. param:: set + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. + + The key attribute size of an SLH-DSA public key is the same as the corresponding private key. + See `PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` and the documentation of each SLH-DSA parameter-set family for details. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_SLH_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + + .. subsection:: Key format + + .. warning:: + + The key format may change in a final version of this API. + The standardization of exchange formats for SHL-DSA public and private keys is in progress, but final documents have not been published. + See :cite-title:`LAMPS-SLHDSA`. + + The current proposed format is based on the current expected outcome of that process. + + A SLH-DSA public key is defined in `[FIPS205]` §9.1 as two :math:`n`\ -byte values, :math:`PK\text{.seed}` and :math:`PK\text{.root}`, where :math:`n` is the security parameter. + + The data format for export of the public key is the concatenation of the two octet strings: + + .. math:: + + PK\text{.seed}\ ||\ PK\text{.root} + +.. macro:: PSA_SLH_DSA_FAMILY_SHA2_S + :definition: ((psa_slh_dsa_family_t) 0x02) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHA2-\ *NNN*\ s parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHA2-128s : ``key_bits = 128`` + * SLH-DSA-SHA2-192s : ``key_bits = 192`` + * SLH-DSA-SHA2-256s : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHA2_F + :definition: ((psa_slh_dsa_family_t) 0x04) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHA2-\ *NNN*\ f parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHA2-128f : ``key_bits = 128`` + * SLH-DSA-SHA2-192f : ``key_bits = 192`` + * SLH-DSA-SHA2-256f : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHAKE_S + :definition: ((psa_slh_dsa_family_t) 0x0b) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHAKE-\ *NNN*\ s parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHAKE-128s : ``key_bits = 128`` + * SLH-DSA-SHAKE-192s : ``key_bits = 192`` + * SLH-DSA-SHAKE-256s : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHAKE_F + :definition: ((psa_slh_dsa_family_t) 0x0d) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHAKE-\ *NNN*\ f parameter sets. + + This family comprises the following parameter sets: + + * SLH-DSA-SHAKE-128f : ``key_bits = 128`` + * SLH-DSA-SHAKE-192f : ``key_bits = 192`` + * SLH-DSA-SHAKE-256f : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA key, either a key pair or a public key. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA key pair. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA public key. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_GET_FAMILY + :definition: /* specification-defined value */ + + .. summary:: + Extract the parameter-set family from an SLH-DSA key type. + + .. param:: type + An SLH-DSA key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SLH_DSA(type)` is true. + + .. return:: psa_dh_family_t + The SLH-DSA parameter-set family id, if ``type`` is a supported SLH-DSA key. Unspecified if ``type`` is not a supported SLH-DSA key. + .. _dh-keys: Diffie Hellman keys @@ -1266,34 +1512,6 @@ Diffie Hellman keys These groups are defined by :rfc-title:`7919#A`. -.. macro:: PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY - :definition: /* specification-defined value */ - - .. summary:: - The key pair type corresponding to a public key type. - - .. param:: type - A public key type or key pair type. - - .. return:: - The corresponding key pair type. If ``type`` is not a public key or a key pair, the return value is undefined. - - If ``type`` is a key pair type, it will be left unchanged. - -.. macro:: PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR - :definition: /* specification-defined value */ - - .. summary:: - The public key type corresponding to a key pair type. - - .. param:: type - A public key type or key pair type. - - .. return:: - The corresponding public key type. If ``type`` is not a public key or a key pair, the return value is undefined. - - If ``type`` is a public key type, it will be left unchanged. - .. macro:: PSA_KEY_TYPE_IS_DH :definition: /* specification-defined value */ diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 98517b75..220b49b0 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -233,7 +233,9 @@ Support macros The following composite algorithms require a hash algorithm: * `PSA_ALG_DETERMINISTIC_ECDSA()` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` * `PSA_ALG_ECDSA()` + * `PSA_ALG_HASH_SLH_DSA()` * `PSA_ALG_HKDF()` * `PSA_ALG_HKDF_EXPAND()` * `PSA_ALG_HKDF_EXTRACT()` diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index 9f2e7089..15af5ae3 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -178,13 +178,26 @@ Hash algorithms SHA3-512 is defined in :cite:`FIPS202`. +.. macro:: PSA_ALG_SHAKE128_256 + :definition: ((psa_algorithm_t)0x02000016) + + .. summary:: + The first 256 bits (32 bytes) of the SHAKE128 output. + + This can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`). + + SHAKE128 is defined in :cite:`FIPS202`. + + .. note:: + For other scenarios where a hash function based on SHA3 or SHAKE is required, SHA3-256 is recommended. SHA3-256 has the same output size, and a theoretically higher security strength. + .. macro:: PSA_ALG_SHAKE256_512 :definition: ((psa_algorithm_t)0x02000015) .. summary:: The first 512 bits (64 bytes) of the SHAKE256 output. - This is the prehashing for Ed448ph (see `PSA_ALG_ED448PH`). + This is the pre-hashing for Ed448ph (see `PSA_ALG_ED448PH`), and can be used as pre-hashing for SLH-DSA (see `PSA_ALG_HASH_SLH_DSA()`). SHAKE256 is defined in :cite:`FIPS202`. diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index d802a9ea..bd24d03c 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -22,6 +22,11 @@ There are two pairs of single-part functions for asymmetric signature: Asymmetric signature algorithms ------------------------------- +.. _rsa-sign-algorithms: + +RSA signature algorithms +^^^^^^^^^^^^^^^^^^^^^^^^ + .. macro:: PSA_ALG_RSA_PKCS1V15_SIGN :definition: /* specification-defined value */ @@ -146,6 +151,77 @@ Asymmetric signature algorithms | `PSA_KEY_TYPE_RSA_KEY_PAIR` | `PSA_KEY_TYPE_RSA_PUBLIC_KEY` (signature verification only) +.. macro:: PSA_ALG_IS_RSA_PKCS1V15_SIGN + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an RSA PKCS#1 v1.5 signature algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_RSA_PSS + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is an RSA PSS signature algorithm. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an RSA PSS signature algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + This macro returns ``1`` for algorithms constructed using either `PSA_ALG_RSA_PSS()` or `PSA_ALG_RSA_PSS_ANY_SALT()`. + +.. macro:: PSA_ALG_IS_RSA_PSS_ANY_SALT + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an RSA PSS signature algorithm that permits any salt length, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + An RSA PSS signature algorithm that permits any salt length is constructed using `PSA_ALG_RSA_PSS_ANY_SALT()`. + + See also `PSA_ALG_IS_RSA_PSS()` and `PSA_ALG_IS_RSA_PSS_STANDARD_SALT()`. + +.. macro:: PSA_ALG_IS_RSA_PSS_STANDARD_SALT + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an RSA PSS signature algorithm that requires the standard salt length, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + An RSA PSS signature algorithm that requires the standard salt length is constructed using `PSA_ALG_RSA_PSS()`. + + See also `PSA_ALG_IS_RSA_PSS()` and `PSA_ALG_IS_RSA_PSS_ANY_SALT()`. + +.. _ecc-sign-algorithms: + +Elliptic curve signature algorithms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + .. macro:: PSA_ALG_ECDSA :definition: /* specification-defined value */ @@ -347,6 +423,351 @@ Asymmetric signature algorithms When used with `psa_sign_hash()` or `psa_verify_hash()`, the ``hash`` parameter to the call should be used as :math:`\text{PH}(M)` in the algorithms defined in :RFC:`8032#5.2`. +.. macro:: PSA_ALG_IS_ECDSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is ECDSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an ECDSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_DETERMINISTIC_ECDSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic ECDSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic ECDSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_ECDSA()` and `PSA_ALG_IS_RANDOMIZED_ECDSA()`. + +.. macro:: PSA_ALG_IS_RANDOMIZED_ECDSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is randomized ECDSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a randomized ECDSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_ECDSA()` and `PSA_ALG_IS_DETERMINISTIC_ECDSA()`. + +.. macro:: PSA_ALG_IS_HASH_EDDSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is HashEdDSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a HashEdDSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. _slh-dsa-algorithms: + +Stateless Hash-based signature algorithms +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The SLH-DSA signature and verification scheme is defined in :cite-title:`FIPS205`. +SLH-DSA has twelve parameter sets which provide differing security strengths, trade-off between signature size and computation cost, and selection between SHA2 and SHAKE-based hashing. + +SLH-DSA keys are fairly compact, 32, 48, or 64 bytes for the public key, and double that for the key pair. +SLH-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 7.8kB and 49kB depending on the selected parameter set. +An SLH-DSA signature has the structure described in `[FIPS205]` §9.2, Figure 17. + +See `[FIPS205]` §11 for details on the parameter sets, and the public key and generated signature sizes. + +The generation of an SLH-DSA key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`slh-dsa-keys`. + +`[FIPS205]` defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. +Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_ALG_DETERMINISTIC_SLH_DSA`, `PSA_ALG_HASH_SLH_DSA()`, and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`. + +.. _slh-dsa-deterministic-signatures: + +.. rubric:: Hedged and deterministic signatures + +Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. +Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs. + +Signature verification does not distinguish between a hedged and a deterministic signature. +Either hedged or deterministic algorithms can be used when verifying a signature. + +When computing a signature, the key's permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. +When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key's permitted-algorithm policy. + +.. note:: + + The hedged version provides message secrecy and some protection against side-channels. + `[FIPS205]` recommends that users should use the hedged version if either of these issues are a concern. + The deterministic variant should only be used if the implementation does not include any source of randomness. + +.. admonition:: Implementation note + + `[FIPS205]` recommends that implementations use an approved random number generator to provide the random value in the hedged version. + However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant. + +.. rationale:: + + The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in `[FIPS205]`. + + However, the |API| gives distinct algorithm identifiers for the hedged and deterministic variants for the following reasons: + + * `[FIPS205]` §9.1 recommends that SLH-DSA signing keys are only used to compute either deterministic, or hedged, signatures, but not both. + Supporting this recommendation requires separate algorithm identifiers, and requiring an exact policy match for signature computation. + * Enable an application use case to require a specific variant. + +.. rubric:: Pure and pre-hashed algorithms + +The pre-hashed signature computation *HashSLH-DSA* generates distinct signatures to a pure signature *SLH-DSA*, with the same key and message hashing algorithm. + +An SLH-DSA signature can only be verified with an SLH-DSA algorithm. A HashSLH-DSA signature can only be verified with a HashSLH-DSA algorithm. + +.. rubric:: Contexts + +Contexts are not supported in the current version of this specification because there is no suitable signature interface that can take the context as a parameter. +A empty context string is used when computing or verifying SLH-DSA signatures. + +A future version of this specification may add suitable functions and extend this algorithm to support contexts. + +.. macro:: PSA_ALG_SLH_DSA + :definition: ((psa_algorithm_t) 0x06004000) + + .. summary:: + Stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA). + + This algorithm can be only used with the `psa_sign_message()` and `psa_verify_message()` functions. + + This is the pure SLH-DSA digital signature algorithm, defined by :cite-title:`FIPS205`, using hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + When `PSA_ALG_SLH_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_SLH_DSA` as the algorithm in a call to `psa_sign_message()`. + * `PSA_ALG_SLH_DSA` or `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to `psa_verify_message()`. + + .. note:: + To sign or verify the pre-computed hash of a message using SLH-DSA, the HashSLH-DSA algorithms (`PSA_ALG_HASH_SLH_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`) can also be used with `psa_sign_hash()` and `psa_verify_hash()`. + + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_SLH_DSA + :definition: ((psa_algorithm_t) 0x06004100) + + .. summary:: + Deterministic stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA). + + This algorithm can be only used with the `psa_sign_message()` and `psa_verify_message()` functions. + + This is the pure SLH-DSA digital signature algorithm, defined by `[FIPS205]`, without hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_SLH_DSA` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + When `PSA_ALG_DETERMINISTIC_SLH_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to `psa_sign_message()`. + * `PSA_ALG_SLH_DSA` or `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to `psa_verify_message()`. + + .. note:: + To sign or verify the pre-computed hash of a message using SLH-DSA, the HashSLH-DSA algorithms (`PSA_ALG_HASH_SLH_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`) can also be used with `psa_sign_hash()` and `psa_verify_hash()`. + + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA). + + .. param:: hash_alg + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes `PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding HashSLH-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed SLH-DSA digital signature algorithm, defined by `[FIPS205]`, using hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS205]` §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + When `PSA_ALG_HASH_SLH_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_HASH_SLH_DSA()` as the algorithm in a call to `psa_sign_message()` and `psa_sign_hash()`. + * `PSA_ALG_HASH_SLH_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to `psa_verify_message()` and `psa_verify_hash()`. + + .. note:: + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Usage + + This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches: + + * Call `psa_sign_message()` with the message. + + * Calculate the hash of the message with `psa_hash_compute()`, or with a multi-part hash operation, using the ``hash_alg`` hash algorithm. + Note that ``hash_alg`` can be extracted from the signature algorithm using :code:`PSA_ALG_GET_HASH(sig_alg)`. + Then sign the calculated hash with `psa_sign_hash()`. + + Verifying a signature is similar, using `psa_verify_message()` or `psa_verify_hash()` instead of the signature function. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Deterministic stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA). + + .. param:: hash_alg + A hash algorithm: a value of type `psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes `PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding deterministic HashSLH-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed SLH-DSA digital signature algorithm, defined by `[FIPS205]`, without hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS205]` §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_HASH_SLH_DSA()` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + When `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to `psa_sign_message()` and `psa_sign_hash()`. + * `PSA_ALG_HASH_SLH_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to `psa_verify_message()` and `psa_verify_hash()`. + + .. note:: + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Usage + + See `PSA_ALG_HASH_SLH_DSA()` for example usage. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is SLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an SLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_HEDGED_HASH_SLH_DSA()`. + +.. macro:: PSA_ALG_IS_HEDGED_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is hedged HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a hedged HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA()`. + Asymmetric signature functions ------------------------------ @@ -635,132 +1056,6 @@ Support macros This includes all algorithms such that `PSA_ALG_IS_HASH_AND_SIGN()` is true, as well as signature algorithms for which the input to `psa_sign_hash()` or `psa_verify_hash()` is not directly a hash, such as `PSA_ALG_IS_RSA_PKCS1V15_SIGN`. -.. macro:: PSA_ALG_IS_RSA_PKCS1V15_SIGN - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is an RSA PKCS#1 v1.5 signature algorithm. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is an RSA PKCS#1 v1.5 signature algorithm, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - -.. macro:: PSA_ALG_IS_RSA_PSS - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is an RSA PSS signature algorithm. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is an RSA PSS signature algorithm, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - - This macro returns ``1`` for algorithms constructed using either `PSA_ALG_RSA_PSS()` or `PSA_ALG_RSA_PSS_ANY_SALT()`. - -.. macro:: PSA_ALG_IS_RSA_PSS_ANY_SALT - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is an RSA PSS signature algorithm that permits any salt length. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is an RSA PSS signature algorithm that permits any salt length, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - - An RSA PSS signature algorithm that permits any salt length is constructed using `PSA_ALG_RSA_PSS_ANY_SALT()`. - - See also `PSA_ALG_IS_RSA_PSS()` and `PSA_ALG_IS_RSA_PSS_STANDARD_SALT()`. - -.. macro:: PSA_ALG_IS_RSA_PSS_STANDARD_SALT - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is an RSA PSS signature algorithm that requires the standard salt length. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is an RSA PSS signature algorithm that requires the standard salt length, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - - An RSA PSS signature algorithm that requires the standard salt length is constructed using `PSA_ALG_RSA_PSS()`. - - See also `PSA_ALG_IS_RSA_PSS()` and `PSA_ALG_IS_RSA_PSS_ANY_SALT()`. - -.. macro:: PSA_ALG_IS_ECDSA - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is ECDSA. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is an ECDSA algorithm, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - -.. macro:: PSA_ALG_IS_DETERMINISTIC_ECDSA - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is deterministic ECDSA. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is a deterministic ECDSA algorithm, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - - See also `PSA_ALG_IS_ECDSA()` and `PSA_ALG_IS_RANDOMIZED_ECDSA()`. - -.. macro:: PSA_ALG_IS_RANDOMIZED_ECDSA - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is randomized ECDSA. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is a randomized ECDSA algorithm, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - - See also `PSA_ALG_IS_ECDSA()` and `PSA_ALG_IS_DETERMINISTIC_ECDSA()`. - -.. macro:: PSA_ALG_IS_HASH_EDDSA - :definition: /* specification-defined value */ - - .. summary:: - Whether the specified algorithm is HashEdDSA. - - .. param:: alg - An algorithm identifier: a value of type `psa_algorithm_t`. - - .. return:: - ``1`` if ``alg`` is a HashEdDSA algorithm, ``0`` otherwise. - - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. - .. macro:: PSA_ALG_IS_HASH_AND_SIGN :definition: /* specification-defined value */ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index a1784f9a..272ab71e 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -130,6 +130,7 @@ The defined values for HASH-TYPE are shown in :numref:`table-hash-type`. SHA3-512, ``0x13``, `PSA_ALG_SHA3_512`, ``0x02000013`` SM3, ``0x14``, `PSA_ALG_SM3`, ``0x02000014`` SHAKE256-512, ``0x15``, `PSA_ALG_SHAKE256_512`, ``0x02000015`` + SHAKE128-256, ``0x16``, `PSA_ALG_SHAKE128_256`, ``0x02000016`` *wildcard* :sup:`a`, ``0xFF``, `PSA_ALG_ANY_HASH`, ``0x020000FF`` a. 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. @@ -308,17 +309,21 @@ H = HASH-TYPE (see :numref:`table-hash-type`) for message signature algorithms t :widths: auto Signature algorithm, SIGN-TYPE, Algorithm identifier, Algorithm value - RSA PKCS#1 v1.5, ``0x02``, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(hash_alg)`, ``0x060002hh`` :sup:`a` + RSA PKCS#1 v1.5, ``0x02``, :code:`PSA_ALG_RSA_PKCS1V15_SIGN(hash)`, ``0x060002hh`` :sup:`a` RSA PKCS#1 v1.5 no hash :sup:`b`, ``0x02``, `PSA_ALG_RSA_PKCS1V15_SIGN_RAW`, ``0x06000200`` - RSA PSS, ``0x03``, :code:`PSA_ALG_RSA_PSS(hash_alg)`, ``0x060003hh`` :sup:`a` - RSA PSS any salt length, ``0x13``, :code:`PSA_ALG_RSA_PSS_ANY_SALT(hash_alg)`, ``0x060013hh`` :sup:`a` - Randomized ECDSA, ``0x06``, :code:`PSA_ALG_ECDSA(hash_alg)`, ``0x060006hh`` :sup:`a` + RSA PSS, ``0x03``, :code:`PSA_ALG_RSA_PSS(hash)`, ``0x060003hh`` :sup:`a` + RSA PSS any salt length, ``0x13``, :code:`PSA_ALG_RSA_PSS_ANY_SALT(hash)`, ``0x060013hh`` :sup:`a` + Randomized ECDSA, ``0x06``, :code:`PSA_ALG_ECDSA(hash)`, ``0x060006hh`` :sup:`a` Randomized ECDSA no hash :sup:`b`, ``0x06``, `PSA_ALG_ECDSA_ANY`, ``0x06000600`` - Deterministic ECDSA, ``0x07``, :code:`PSA_ALG_DETERMINISTIC_ECDSA(hash_alg)`, ``0x060007hh`` :sup:`a` + Deterministic ECDSA, ``0x07``, :code:`PSA_ALG_DETERMINISTIC_ECDSA(hash)`, ``0x060007hh`` :sup:`a` PureEdDSA, ``0x08``, `PSA_ALG_PURE_EDDSA`, ``0x06000800`` HashEdDSA, ``0x09``, `PSA_ALG_ED25519PH` and `PSA_ALG_ED448PH`, ``0x060009hh`` :sup:`c` + Hedged SLH-DSA, ``0x40``, `PSA_ALG_SLH_DSA`, ``0x06004000`` + Deterministic SLH-DSA, ``0x41``, `PSA_ALG_DETERMINISTIC_SLH_DSA`, ``0x06004100`` + Hedged HashSLH-DSA, ``0x42``, :code:`PSA_ALG_HASH_SLH_DSA(hash)`, ``0x060042hh`` :sup:`a` + Deterministic HashSLH-DSA, ``0x43``, :code:`PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash)`, ``0x060043hh`` :sup:`a` -a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash_alg``, used to construct the signature algorithm. +a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash``, used to construct the signature algorithm. b. Asymmetric signature algorithms without hashing can only be used with `psa_sign_hash()` and `psa_verify_hash()`. @@ -569,6 +574,7 @@ The defined values for FAMILY depend on the ASYM-TYPE value. See the details for Asymmetric key type, ASYM-TYPE, Details Non-parameterized, 0, See :secref:`simple-asymmetric-key-encoding` Elliptic Curve, 2, See :secref:`ecc-key-encoding` + SLH-DSA, 3, See :secref:`slh-dsa-key-encoding` Diffie-Hellman, 4, See :secref:`dh-key-encoding` SPAKE2+, 8, See :secref:`spakep2-key-encoding` @@ -634,6 +640,36 @@ The defined values for ECC-FAMILY and P are shown in :numref:`table-ecc-type`. a. 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 :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` as required. +.. _slh-dsa-key-encoding: + +SLH-DSA key encoding +^^^^^^^^^^^^^^^^^^^^ + +The key type for SLH-DSA keys defined in this specification are encoded as shown in :numref:`fig-slh-dsa-key-fields`. + +.. figure:: ../figure/encoding/slh_dsa_key.* + :name: fig-slh-dsa-key-fields + + SLH-DSA key encoding + +PAIR is either 0 for a public key, or 3 for a key pair. + +The defined values for FAMILY and P are shown in :numref:`table-slh-dsa-type`. + +.. csv-table:: SLH-DSA key family values + :name: table-slh-dsa-type + :header-rows: 1 + :align: left + :widths: auto + + SLH-DSA key family, FAMILY, P, SLH-DSA family :sup:`a`, Public key value, Key pair value + SLH-DSA-SHA2-\ *N*\ s, 0x01, 0, `PSA_SLH_DSA_FAMILY_SHA2_S`, ``0x4182``, ``0x7182`` + SLH-DSA-SHA2-\ *N*\ f, 0x02, 0, `PSA_SLH_DSA_FAMILY_SHA2_F`, ``0x4184``, ``0x7184`` + SLH-DSA-SHAKE-\ *N*\ s, 0x05, 1, `PSA_SLH_DSA_FAMILY_SHAKE_S`, ``0x418b``, ``0x718b`` + SLH-DSA-SHAKE-\ *N*\ f, 0x06, 1, `PSA_SLH_DSA_FAMILY_SHAKE_F`, ``0x418d``, ``0x718d`` + +a. The SLH-DSA family values defined in the API also include the parity bit. The key type value is constructed from the SLH-DSA family using either :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(family)` as required. + .. _dh-key-encoding: Diffie Hellman key encoding diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index a0e7d299..63c6c2b3 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -33,6 +33,9 @@ Changes to the API See :secref:`asymmetric-key-encoding` and :secref:`appendix-specdef-key-values`. +* Added support for FIPS 205 SLH-DSA signature algorithm and keys. + See :secref:`slh-dsa-keys` and :secref:`slh-dsa-algorithms`. + Clarifications and fixes ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index 11d1ea2d..71d165d1 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -39,6 +39,9 @@ Algorithm macros #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \ ((psa_algorithm_t) (0x06000700 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004300 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_ECDSA(hash_alg) \ ((psa_algorithm_t) (0x06000600 | ((hash_alg) & 0x000000ff))) @@ -48,6 +51,9 @@ Algorithm macros #define PSA_ALG_GET_HASH(alg) \ (((alg) & 0x000000ff) == 0 ? PSA_ALG_NONE : 0x02000000 | ((alg) & 0x000000ff)) + #define PSA_ALG_HASH_SLH_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004200 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_HKDF(hash_alg) \ ((psa_algorithm_t) (0x08000100 | ((hash_alg) & 0x000000ff))) @@ -78,6 +84,9 @@ Algorithm macros #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000700) + #define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004300) + #define PSA_ALG_IS_ECDH(alg) \ (((alg) & 0x7fff0000) == 0x09020000) @@ -92,11 +101,18 @@ Algorithm macros #define PSA_ALG_IS_HASH_AND_SIGN(alg) \ (PSA_ALG_IS_RSA_PSS(alg) || PSA_ALG_IS_RSA_PKCS1V15_SIGN(alg) || \ - PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg)) + PSA_ALG_IS_ECDSA(alg) || PSA_ALG_IS_HASH_EDDSA(alg) || \ + PSA_ALG_IS_HASH_SLH_DSA(alg)) #define PSA_ALG_IS_HASH_EDDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000900) + #define PSA_ALG_IS_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000001ff) == 0x06004200) + + #define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004200) + #define PSA_ALG_IS_HKDF(alg) \ (((alg) & ~0x000000ff) == 0x08000100) @@ -152,12 +168,16 @@ Algorithm macros (((alg) & 0x7f000000) == 0x06000000) #define PSA_ALG_IS_SIGN_HASH(alg) \ - PSA_ALG_IS_SIGN(alg) + (PSA_ALG_IS_SIGN(alg) && \ + (alg) != PSA_ALG_PURE_EDDSA && !PSA_ALG_IS_SLH_DSA(alg)) #define PSA_ALG_IS_SIGN_MESSAGE(alg) \ (PSA_ALG_IS_SIGN(alg) && \ (alg) != PSA_ALG_ECDSA_ANY && (alg) != PSA_ALG_RSA_PKCS1V15_SIGN_RAW) + #define PSA_ALG_IS_SLH_DSA(alg) \ + (((alg) & ~0x00000100) == 0x06004000) + #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08000700) @@ -304,6 +324,15 @@ Key type macros #define PSA_KEY_TYPE_IS_RSA(type) \ (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001) + #define PSA_KEY_TYPE_IS_SLH_DSA(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4180) + + #define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ + (((type) & 0xff80) == 0x7180) + + #define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ + (((type) & 0xff80) == 0x4180) + #define PSA_KEY_TYPE_IS_SPAKE2P(type) \ ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4400) @@ -322,6 +351,15 @@ Key type macros #define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ ((psa_key_type_t) ((type) & ~0x3000)) + #define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) \ + ((psa_slh_dsa_family_t) ((type) & 0x007f)) + + #define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) \ + ((psa_key_type_t) (0x7180 | ((set) & 0x007f))) + + #define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) \ + ((psa_key_type_t) (0x4180 | ((set) & 0x007f))) + #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) \ ((psa_ecc_family_t) ((type) & 0x007f)) diff --git a/doc/crypto/figure/encoding/slh_dsa_key.json b/doc/crypto/figure/encoding/slh_dsa_key.json new file mode 100644 index 00000000..4370da1d --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "FAMILY", "bits": 6 }, + { "name": "3", "bits": 5 }, + { "name": "PAIR", "bits": 2 }, + { "name": "1", "bits": 1 }, + { "name": "0", "bits": 1 } + ], + "options": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "bits": 16, + "vspace": 52, + "hspace": 300 + } +} diff --git a/doc/crypto/figure/encoding/slh_dsa_key.json.license b/doc/crypto/figure/encoding/slh_dsa_key.json.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/slh_dsa_key.pdf b/doc/crypto/figure/encoding/slh_dsa_key.pdf new file mode 100644 index 00000000..eab4b8a2 Binary files /dev/null and b/doc/crypto/figure/encoding/slh_dsa_key.pdf differ diff --git a/doc/crypto/figure/encoding/slh_dsa_key.pdf.license b/doc/crypto/figure/encoding/slh_dsa_key.pdf.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.pdf.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/slh_dsa_key.svg b/doc/crypto/figure/encoding/slh_dsa_key.svg new file mode 100644 index 00000000..7610f237 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.svg @@ -0,0 +1,2 @@ + +01671112131415PFAMILY3PAIR10 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/slh_dsa_key.svg.license b/doc/crypto/figure/encoding/slh_dsa_key.svg.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/references b/doc/crypto/references index 196e15df..84425b10 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -396,3 +396,15 @@ :author: Thread Group :publication: July 2022 :url: www.threadgroup.org/ThreadSpec + +.. reference:: FIPS205 + :title: FIPS Publication 205: Stateless Hash-Based Digital Signature Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.205 + +.. reference:: LAMPS-SLHDSA + :title: Internet X.509 Public Key Infrastructure: Algorithm Identifiers for SLH-DSA (Draft 02) + :author: IETF + :publication: October 2024 (DRAFT) + :url: datatracker.ietf.org/doc/draft-ietf-lamps-x509-slhdsa-02