From c67d3cc1f39425a2615fbcab25d8a74102956e4f Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 18 Sep 2024 17:03:44 +0100 Subject: [PATCH 01/10] Move scheme-specific support macros in Asymmetric Signature chapter --- doc/crypto/api/ops/signature.rst | 262 ++++++++++++++++--------------- 1 file changed, 136 insertions(+), 126 deletions(-) diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index d802a9ea..e561f9fa 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,66 @@ 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. + Asymmetric signature functions ------------------------------ @@ -635,132 +771,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 */ From 121faf7fb264042be53303ce1cf3880a8f27ecd6 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 18 Sep 2024 18:22:33 +0100 Subject: [PATCH 02/10] Fix error in PSA_ALG_IS_SIGN_HASH() to exclude PureEDDSA --- doc/crypto/appendix/specdef_values.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index 11d1ea2d..e9110396 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -152,7 +152,8 @@ 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) #define PSA_ALG_IS_SIGN_MESSAGE(alg) \ (PSA_ALG_IS_SIGN(alg) && \ From 22a39f87d6a11f2c9de062a44c0cb5dda7b5390b Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Wed, 18 Sep 2024 20:54:15 +0100 Subject: [PATCH 03/10] Define key types and algorithms for FIPS 205 SLH-DSA --- doc/crypto/api.db/psa/crypto.h | 22 ++ doc/crypto/api/keys/types.rst | 263 ++++++++++++++++-- doc/crypto/api/ops/algorithms.rst | 2 + doc/crypto/api/ops/hash.rst | 15 +- doc/crypto/api/ops/signature.rst | 243 ++++++++++++++++ doc/crypto/appendix/encodings.rst | 48 +++- doc/crypto/appendix/history.rst | 3 + doc/crypto/appendix/specdef_values.rst | 44 ++- doc/crypto/figure/encoding/slh_key.json | 18 ++ .../figure/encoding/slh_key.json.license | 2 + doc/crypto/figure/encoding/slh_key.pdf | Bin 0 -> 7375 bytes .../figure/encoding/slh_key.pdf.license | 2 + doc/crypto/figure/encoding/slh_key.svg | 2 + .../figure/encoding/slh_key.svg.license | 2 + doc/crypto/references | 6 + 15 files changed, 634 insertions(+), 38 deletions(-) create mode 100644 doc/crypto/figure/encoding/slh_key.json create mode 100644 doc/crypto/figure/encoding/slh_key.json.license create mode 100644 doc/crypto/figure/encoding/slh_key.pdf create mode 100644 doc/crypto/figure/encoding/slh_key.pdf.license create mode 100644 doc/crypto/figure/encoding/slh_key.svg create mode 100644 doc/crypto/figure/encoding/slh_key.svg.license diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index 8cc8cf5c..d4841e68 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_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,14 @@ 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_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_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 */ @@ -110,7 +117,9 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_MAC(alg) /* specification-defined value */ #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */ #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */ +#define PSA_ALG_IS_PURE_SLH_DSA(alg) /* specification-defined value */ #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_RANDOMIZED_SLH_DSA(alg) /* specification-defined value */ #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \ PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg) #define PSA_ALG_IS_RSA_OAEP(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,9 @@ 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(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_KEY_PAIR(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_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 +331,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_GET_FAMILY(type) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_KEY_PAIR(set) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_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 +391,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_FAMILY_SHA2_F ((psa_slh_family_t) 0x04) +#define PSA_SLH_FAMILY_SHA2_S ((psa_slh_family_t) 0x02) +#define PSA_SLH_FAMILY_SHAKE_F ((psa_slh_family_t) 0x0d) +#define PSA_SLH_FAMILY_SHAKE_S ((psa_slh_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..ec13a06f 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-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,210 @@ 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-keys: + +Stateless Hash keys +------------------- + +.. typedef:: uint8_t psa_slh_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 key using the `PSA_KEY_TYPE_SLH_KEY_PAIR()` or `PSA_KEY_TYPE_SLH_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 family identifier values is divided as follows: + + :code:`0x00` + Reserved. + Not allocated to an SLH parameter-set family. + :code:`0x01 - 0x7f` + SLH 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 family identifier is a parity bit for the whole key type. + See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types. + + .. admonition:: Implementation note + + To provide other SLH parameter sets, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type. + +.. macro:: PSA_KEY_TYPE_SLH_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + SLH key pair: both the private key and public key. + + .. param:: set + A value of type `psa_slh_family_t` that identifies the SLH parameter-set family to be used. + + The size of of an SLH key pair is the bit-size of each element in the SLH-DSA keys defined in :cite-title:`FIPS205`. + That is, for a parameter set with security parameter :math:`n`, the bit-size in the key attributes is :math:`8n`. + Also see the documentation of each SLH 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 + + A SLH-DSA key-pair is defined in :cite:`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_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`. + + .. subsection:: Key derivation + + :issue:`TBD` + + .. todo:: + + SLH-DSA key generation requires three :math:`n`\ -byte random values --- so these *could* be extracted from a suitable KDF in sequence or via separate derivation using different labels. + + However, there does not seem to be any defined standard approach. + + We could define this as permitted, but with imp-def semantics, enabling key-pair generation from a device secret, for example. + +.. macro:: PSA_KEY_TYPE_SLH_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + SLH public key. + + .. param:: set + A value of type `psa_slh_family_t` that identifies the SLH parameter-set family to be used. + + The size of an SLH public key is the same as the corresponding private key. See `PSA_KEY_TYPE_SLH_KEY_PAIR()` and the documentation of each SLH 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 + + A SLH-DSA public key is defined in :cite:`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_FAMILY_SHA2_S + :definition: ((psa_slh_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 :cite-title:`FIPS205`. + +.. macro:: PSA_SLH_FAMILY_SHA2_F + :definition: ((psa_slh_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 :cite:`FIPS205`. + +.. macro:: PSA_SLH_FAMILY_SHAKE_S + :definition: ((psa_slh_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 :cite:`FIPS205`. + +.. macro:: PSA_SLH_FAMILY_SHAKE_F + :definition: ((psa_slh_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 :cite:`FIPS205`. + +.. macro:: PSA_KEY_TYPE_IS_SLH + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH 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_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH key pair. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH public key. + + .. param:: type + A key type: a value of type `psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_SLH_GET_FAMILY + :definition: /* specification-defined value */ + + .. summary:: + Extract the parameter-set family from an SLH key type. + + .. param:: type + An SLH key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SLH(type)` is true. + + .. return:: psa_dh_family_t + The SLH parameter-set family id, if ``type`` is a supported SLH key. Unspecified if ``type`` is not a supported SLH key. + .. _dh-keys: Diffie Hellman keys @@ -1266,34 +1499,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 e561f9fa..03f12dc3 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -483,6 +483,249 @@ Elliptic curve signature algorithms 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`. +:cite:`FIPS205` defines 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 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 :cite:`FIPS205` §9.2, Figure 17. + +See :cite:`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-keys`. + +:cite:`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()`. + +* The pre-hashed signature computation generates distinct signatures to a pure signature, even with the same key and message hashing algorithm. + + When verifying a signature it is necessary to know which algorithm was used to generate it. + +* Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every siging 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 form of algorithm can be used when verifying a signature. + +.. note:: + 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), using hedging. + + 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 key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + + .. note:: + See the general comments in :secref:`slh-dsa-algorithms`. + + .. 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_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_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 :cite-title:`FIPS205`, without hedging. + SLH-DSA requires an SLH 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. + + .. note:: + See the general comments in :secref:`slh-dsa-algorithms`. + + .. 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_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_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), using hedging. + + .. 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 :cite-title:`FIPS205`, using hedging. + SLH-DSA requires an SLH key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + + .. note:: + See the general comments in :secref:`slh-dsa-algorithms`. + + .. 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_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_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 :cite-title:`FIPS205`, without hedging. + SLH-DSA requires an SLH 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. + + .. note:: + See the general comments in :secref:`slh-dsa-algorithms`. + + .. 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_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is SLH-DSA or HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an SLH-DSA or 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_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic SLH-DSA or HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic SLH-DSA or 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_SLH_DSA()` and `PSA_ALG_IS_RANDOMIZED_SLH_DSA()`. + +.. macro:: PSA_ALG_IS_RANDOMIZED_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is randomized SLH-DSA or HashSLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a randomized SLH-DSA or 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_SLH_DSA()` and `PSA_ALG_IS_DETERMINISTIC_SLH_DSA()`. + +.. macro:: PSA_ALG_IS_PURE_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is pure SLH-DSA. + + .. param:: alg + An algorithm identifier: a value of type `psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a pure 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. Asymmetric signature functions ------------------------------ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index a1784f9a..41c339da 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-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-key-encoding: + +SLH key encoding +^^^^^^^^^^^^^^^^ + +The key type for SLH-DSA keys defined in this specification are encoded as shown in :numref:`fig-slh-key-fields`. + +.. figure:: ../figure/encoding/slh_key.* + :name: fig-slh-key-fields + + SLH-DSA key encoding + +PAIR is either 0 for a public key, or 3 for a key pair. + +The defined values for SLH-FAMILY and P are shown in :numref:`table-slh-type`. + +.. csv-table:: SLH-DSA key family values + :name: table-slh-type + :header-rows: 1 + :align: left + :widths: auto + + SLH key family, SLH-FAMILY, P, SLH family :sup:`a`, Public key value, Key pair value + SLH-DSA-SHA2-\ *NNN*\ s, 0x01, 0, `PSA_SLH_FAMILY_SHA2_S`, ``0x4182``, ``0x7182`` + SLH-DSA-SHA2-\ *NNN*\ f, 0x02, 0, `PSA_SLH_FAMILY_SHA2_F`, ``0x4184``, ``0x7184`` + SLH-DSA-SHAKE-\ *NNN*\ s, 0x05, 1, `PSA_SLH_FAMILY_SHAKE_S`, ``0x418b``, ``0x718b`` + SLH-DSA-SHAKE-\ *NNN*\ f, 0x06, 1, `PSA_SLH_FAMILY_SHAKE_F`, ``0x418d``, ``0x718d`` + +a. The SLH family values defined in the API also include the parity bit. The key type value is constructed from the SLH family using either :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SLH_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..bae40b26 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-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 e9110396..c1d5fc2d 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_SLH_DSA(alg) \ + (((alg) & ~0x000002ff) == 0x06004100) + #define PSA_ALG_IS_ECDH(alg) \ (((alg) & 0x7fff0000) == 0x09020000) @@ -92,11 +101,15 @@ 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_HKDF(alg) \ (((alg) & ~0x000000ff) == 0x08000100) @@ -130,9 +143,15 @@ Algorithm macros #define PSA_ALG_IS_PBKDF2_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08800100) + #define PSA_ALG_IS_PURE_SLH_DSA(alg) \ + (((alg) & ~0x000001ff) == 0x06004000) + #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000600) + #define PSA_ALG_IS_RANDOMIZED_SLH_DSA(alg) \ + (((alg) & ~0x000002ff) == 0x06004000) + #define PSA_ALG_IS_RSA_OAEP(alg) \ (((alg) & ~0x000000ff) == 0x07000300) @@ -153,12 +172,15 @@ Algorithm macros #define PSA_ALG_IS_SIGN_HASH(alg) \ (PSA_ALG_IS_SIGN(alg) && \ - (alg) != PSA_ALG_PURE_EDDSA) + (alg) != PSA_ALG_PURE_EDDSA && !PSA_ALG_IS_PURE_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) & ~0x000003ff) == 0x06004000) + #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08000700) @@ -305,6 +327,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(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4180) + + #define PSA_KEY_TYPE_IS_SLH_KEY_PAIR(type) \ + (((type) & 0xff80) == 0x7180) + + #define PSA_KEY_TYPE_IS_SLH_PUBLIC_KEY(type) \ + (((type) & 0xff80) == 0x4180) + #define PSA_KEY_TYPE_IS_SPAKE2P(type) \ ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4400) @@ -323,6 +354,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_GET_FAMILY(type) \ + ((psa_ecc_family_t) ((type) & 0x007f)) + + #define PSA_KEY_TYPE_SLH_KEY_PAIR(set) \ + ((psa_key_type_t) (0x7180 | ((set) & 0x007f))) + + #define PSA_KEY_TYPE_SLH_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_key.json b/doc/crypto/figure/encoding/slh_key.json new file mode 100644 index 00000000..c0dd5db1 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "SLH-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_key.json.license b/doc/crypto/figure/encoding/slh_key.json.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_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_key.pdf b/doc/crypto/figure/encoding/slh_key.pdf new file mode 100644 index 0000000000000000000000000000000000000000..ea4a325ecb0b26d91946c1da0a1bae779b652ad0 GIT binary patch literal 7375 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 literal 0 HcmV?d00001 diff --git a/doc/crypto/figure/encoding/slh_key.pdf.license b/doc/crypto/figure/encoding/slh_key.pdf.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_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_key.svg b/doc/crypto/figure/encoding/slh_key.svg new file mode 100644 index 00000000..8520139f --- /dev/null +++ b/doc/crypto/figure/encoding/slh_key.svg @@ -0,0 +1,2 @@ + +01671112131415PSLH-FAMILY3PAIR10 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/slh_key.svg.license b/doc/crypto/figure/encoding/slh_key.svg.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_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..1c1acab6 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -396,3 +396,9 @@ :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 From ecda28efb602c1e9ba31ea16443b286afb3c436a Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 26 Sep 2024 21:43:11 +0100 Subject: [PATCH 04/10] Change key type and family prefix from SLH to SLH-DSA. --- doc/crypto/api/keys/types.rst | 84 +++++++++--------- doc/crypto/api/ops/signature.rst | 28 +++--- doc/crypto/appendix/encodings.rst | 30 +++---- doc/crypto/appendix/history.rst | 2 +- doc/crypto/appendix/specdef_values.rst | 14 +-- .../{slh_key.json => slh_dsa_key.json} | 2 +- ....json.license => slh_dsa_key.json.license} | 0 doc/crypto/figure/encoding/slh_dsa_key.pdf | Bin 0 -> 6982 bytes ...ey.pdf.license => slh_dsa_key.pdf.license} | 0 .../encoding/{slh_key.svg => slh_dsa_key.svg} | 2 +- ...ey.svg.license => slh_dsa_key.svg.license} | 0 doc/crypto/figure/encoding/slh_key.pdf | Bin 7375 -> 0 bytes 12 files changed, 80 insertions(+), 82 deletions(-) rename doc/crypto/figure/encoding/{slh_key.json => slh_dsa_key.json} (89%) rename doc/crypto/figure/encoding/{slh_key.json.license => slh_dsa_key.json.license} (100%) create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.pdf rename doc/crypto/figure/encoding/{slh_key.pdf.license => slh_dsa_key.pdf.license} (100%) rename doc/crypto/figure/encoding/{slh_key.svg => slh_dsa_key.svg} (90%) rename doc/crypto/figure/encoding/{slh_key.svg.license => slh_dsa_key.svg.license} (100%) delete mode 100644 doc/crypto/figure/encoding/slh_key.pdf diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index ec13a06f..e07f3d52 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -592,7 +592,7 @@ The |API| defines the following types of asymmetric key: * :secref:`rsa-keys` * :secref:`ecc-keys` -* :secref:`slh-keys` +* :secref:`slh-dsa-keys` * :secref:`dh-keys` * :secref:`spake2p-keys` @@ -1194,51 +1194,49 @@ 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-keys: +.. _slh-dsa-keys: -Stateless Hash 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_family_t +.. 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 key using the `PSA_KEY_TYPE_SLH_KEY_PAIR()` or `PSA_KEY_TYPE_SLH_PUBLIC_KEY()` macros. + 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 family identifier values is divided as follows: + The range of SLH-DSA family identifier values is divided as follows: :code:`0x00` Reserved. - Not allocated to an SLH parameter-set family. + Not allocated to an SLH-DSA parameter-set family. :code:`0x01 - 0x7f` - SLH parameter-set family identifiers defined by this standard. + 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 family identifier is a parity bit for the whole key type. - See :secref:`asymmetric-key-encoding` for details of the encoding of asymmetric key types. - - .. admonition:: Implementation note - - To provide other SLH parameter sets, it is recommended that an implementation defines a key type with bit 15 set, which indicates an :scterm:`implementation defined` key type. + 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_KEY_PAIR +.. macro:: PSA_KEY_TYPE_SLH_DSA_KEY_PAIR :definition: /* specification-defined value */ .. summary:: - SLH key pair: both the private key and public key. + SLH-DSA key pair: both the private key and public key. .. param:: set - A value of type `psa_slh_family_t` that identifies the SLH parameter-set family to be used. + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. - The size of of an SLH key pair is the bit-size of each element in the SLH-DSA keys defined in :cite-title:`FIPS205`. + The size of of an SLH-DSA key pair is the bit-size of each element in the SLH-DSA keys defined in :cite-title:`FIPS205`. That is, for a parameter set with security parameter :math:`n`, the bit-size in the key attributes is :math:`8n`. - Also see the documentation of each SLH parameter-set family for details. + Also see the documentation of each SLH-DSA parameter-set family for details. .. subsection:: Compatible algorithms @@ -1259,7 +1257,7 @@ Stateless Hash keys SK\text{.seed}\ ||\ SK\text{.prf}\ ||\ PK\text{.seed}\ ||\ PK\text{.root} - See `PSA_KEY_TYPE_SLH_PUBLIC_KEY` for the data format used when exporting the public key with `psa_export_public_key()`. + 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 @@ -1273,16 +1271,16 @@ Stateless Hash keys We could define this as permitted, but with imp-def semantics, enabling key-pair generation from a device secret, for example. -.. macro:: PSA_KEY_TYPE_SLH_PUBLIC_KEY +.. macro:: PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY :definition: /* specification-defined value */ .. summary:: - SLH public key. + SLH-DSA public key. .. param:: set - A value of type `psa_slh_family_t` that identifies the SLH parameter-set family to be used. + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. - The size of an SLH public key is the same as the corresponding private key. See `PSA_KEY_TYPE_SLH_KEY_PAIR()` and the documentation of each SLH parameter-set family for details. + The 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 @@ -1303,8 +1301,8 @@ Stateless Hash keys PK\text{.seed}\ ||\ PK\text{.root} -.. macro:: PSA_SLH_FAMILY_SHA2_S - :definition: ((psa_slh_family_t) 0x02) +.. 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. @@ -1317,8 +1315,8 @@ Stateless Hash keys They are defined in :cite-title:`FIPS205`. -.. macro:: PSA_SLH_FAMILY_SHA2_F - :definition: ((psa_slh_family_t) 0x04) +.. 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. @@ -1331,8 +1329,8 @@ Stateless Hash keys They are defined in :cite:`FIPS205`. -.. macro:: PSA_SLH_FAMILY_SHAKE_S - :definition: ((psa_slh_family_t) 0x0b) +.. 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. @@ -1345,8 +1343,8 @@ Stateless Hash keys They are defined in :cite:`FIPS205`. -.. macro:: PSA_SLH_FAMILY_SHAKE_F - :definition: ((psa_slh_family_t) 0x0d) +.. 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. @@ -1359,44 +1357,44 @@ Stateless Hash keys They are defined in :cite:`FIPS205`. -.. macro:: PSA_KEY_TYPE_IS_SLH +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA :definition: /* specification-defined value */ .. summary:: - Whether a key type is an SLH key, either a key pair or a public key. + 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_KEY_PAIR +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR :definition: /* specification-defined value */ .. summary:: - Whether a key type is an SLH key pair. + 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_PUBLIC_KEY +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY :definition: /* specification-defined value */ .. summary:: - Whether a key type is an SLH public key. + 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_GET_FAMILY +.. macro:: PSA_KEY_TYPE_SLH_DSA_GET_FAMILY :definition: /* specification-defined value */ .. summary:: - Extract the parameter-set family from an SLH key type. + Extract the parameter-set family from an SLH-DSA key type. .. param:: type - An SLH key type: a value of type `psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SLH(type)` is true. + 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 parameter-set family id, if ``type`` is a supported SLH key. Unspecified if ``type`` is not a supported SLH key. + 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: diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index 03f12dc3..b147607b 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -492,13 +492,13 @@ The SLH-DSA signature and verification scheme is defined in :cite-title:`FIPS205 :cite:`FIPS205` defines 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 signatures are much larger than those for RSA and Elliptic curve schemes, between 7.8kB and 49kB depending on the selected parameter set. +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 :cite:`FIPS205` §9.2, Figure 17. See :cite:`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-keys`. +The encoding of each parameter set into the key attributes is described in :secref:`slh-dsa-keys`. :cite:`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()`. @@ -528,7 +528,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 key, which determines the SLH-DSA parameter set for the operation. + 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. @@ -542,8 +542,8 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SLH_KEY_PAIR()` - | :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY()` (signature verification only) + | :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) @@ -554,7 +554,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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`, without hedging. - SLH-DSA requires an SLH key, which determines the SLH-DSA parameter set for the operation. + 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. @@ -568,8 +568,8 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SLH_KEY_PAIR()` - | :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY()` (signature verification only) + | :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 */ @@ -589,7 +589,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 :cite-title:`FIPS205`, using hedging. - SLH-DSA requires an SLH key, which determines the SLH-DSA parameter set for the operation. + 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. @@ -613,8 +613,8 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SLH_KEY_PAIR()` - | :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY()` (signature verification only) + | :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 */ @@ -634,7 +634,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 :cite-title:`FIPS205`, without hedging. - SLH-DSA requires an SLH key, which determines the SLH-DSA parameter set for the operation. + 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. @@ -650,8 +650,8 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. subsection:: Compatible key types - | :code:`PSA_KEY_TYPE_SLH_KEY_PAIR()` - | :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY()` (signature verification only) + | :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 */ diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 41c339da..272ab71e 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -574,7 +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-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` @@ -640,35 +640,35 @@ 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-key-encoding: +.. _slh-dsa-key-encoding: -SLH 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-key-fields`. +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_key.* - :name: fig-slh-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 SLH-FAMILY and P are shown in :numref:`table-slh-type`. +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-type + :name: table-slh-dsa-type :header-rows: 1 :align: left :widths: auto - SLH key family, SLH-FAMILY, P, SLH family :sup:`a`, Public key value, Key pair value - SLH-DSA-SHA2-\ *NNN*\ s, 0x01, 0, `PSA_SLH_FAMILY_SHA2_S`, ``0x4182``, ``0x7182`` - SLH-DSA-SHA2-\ *NNN*\ f, 0x02, 0, `PSA_SLH_FAMILY_SHA2_F`, ``0x4184``, ``0x7184`` - SLH-DSA-SHAKE-\ *NNN*\ s, 0x05, 1, `PSA_SLH_FAMILY_SHAKE_S`, ``0x418b``, ``0x718b`` - SLH-DSA-SHAKE-\ *NNN*\ f, 0x06, 1, `PSA_SLH_FAMILY_SHAKE_F`, ``0x418d``, ``0x718d`` + 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 family values defined in the API also include the parity bit. The key type value is constructed from the SLH family using either :code:`PSA_KEY_TYPE_SLH_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SLH_KEY_PAIR(family)` as required. +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: diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index bae40b26..63c6c2b3 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -34,7 +34,7 @@ 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-keys` and :secref:`slh-dsa-algorithms`. + 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 c1d5fc2d..324ad75e 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -327,13 +327,13 @@ 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(type) \ + #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_KEY_PAIR(type) \ + #define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ (((type) & 0xff80) == 0x7180) - #define PSA_KEY_TYPE_IS_SLH_PUBLIC_KEY(type) \ + #define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ (((type) & 0xff80) == 0x4180) #define PSA_KEY_TYPE_IS_SPAKE2P(type) \ @@ -354,13 +354,13 @@ Key type macros #define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ ((psa_key_type_t) ((type) & ~0x3000)) - #define PSA_KEY_TYPE_SLH_GET_FAMILY(type) \ - ((psa_ecc_family_t) ((type) & 0x007f)) + #define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) \ + ((psa_slh_dsa_family_t) ((type) & 0x007f)) - #define PSA_KEY_TYPE_SLH_KEY_PAIR(set) \ + #define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) \ ((psa_key_type_t) (0x7180 | ((set) & 0x007f))) - #define PSA_KEY_TYPE_SLH_PUBLIC_KEY(set) \ + #define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) \ ((psa_key_type_t) (0x4180 | ((set) & 0x007f))) #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) \ diff --git a/doc/crypto/figure/encoding/slh_key.json b/doc/crypto/figure/encoding/slh_dsa_key.json similarity index 89% rename from doc/crypto/figure/encoding/slh_key.json rename to doc/crypto/figure/encoding/slh_dsa_key.json index c0dd5db1..4370da1d 100644 --- a/doc/crypto/figure/encoding/slh_key.json +++ b/doc/crypto/figure/encoding/slh_dsa_key.json @@ -1,7 +1,7 @@ { "reg": [ { "name": "P", "bits": 1 }, - { "name": "SLH-FAMILY", "bits": 6 }, + { "name": "FAMILY", "bits": 6 }, { "name": "3", "bits": 5 }, { "name": "PAIR", "bits": 2 }, { "name": "1", "bits": 1 }, diff --git a/doc/crypto/figure/encoding/slh_key.json.license b/doc/crypto/figure/encoding/slh_dsa_key.json.license similarity index 100% rename from doc/crypto/figure/encoding/slh_key.json.license rename to doc/crypto/figure/encoding/slh_dsa_key.json.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 0000000000000000000000000000000000000000..eab4b8a2ea76ebf2b9d623aebba4928a404d417c GIT binary patch literal 6982 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 RyGSGqNi86ta!!@{e*pK%e~kbD literal 0 HcmV?d00001 diff --git a/doc/crypto/figure/encoding/slh_key.pdf.license b/doc/crypto/figure/encoding/slh_dsa_key.pdf.license similarity index 100% rename from doc/crypto/figure/encoding/slh_key.pdf.license rename to doc/crypto/figure/encoding/slh_dsa_key.pdf.license diff --git a/doc/crypto/figure/encoding/slh_key.svg b/doc/crypto/figure/encoding/slh_dsa_key.svg similarity index 90% rename from doc/crypto/figure/encoding/slh_key.svg rename to doc/crypto/figure/encoding/slh_dsa_key.svg index 8520139f..7610f237 100644 --- a/doc/crypto/figure/encoding/slh_key.svg +++ b/doc/crypto/figure/encoding/slh_dsa_key.svg @@ -1,2 +1,2 @@ -01671112131415PSLH-FAMILY3PAIR10 \ No newline at end of file +01671112131415PFAMILY3PAIR10 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/slh_key.svg.license b/doc/crypto/figure/encoding/slh_dsa_key.svg.license similarity index 100% rename from doc/crypto/figure/encoding/slh_key.svg.license rename to doc/crypto/figure/encoding/slh_dsa_key.svg.license diff --git a/doc/crypto/figure/encoding/slh_key.pdf b/doc/crypto/figure/encoding/slh_key.pdf deleted file mode 100644 index ea4a325ecb0b26d91946c1da0a1bae779b652ad0..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 7375 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 From b63880a775c7ec068e5c3d9cdb69a550879afda0 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 26 Sep 2024 21:59:08 +0100 Subject: [PATCH 05/10] fixup: update api header --- doc/crypto/api.db/psa/crypto.h | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index d4841e68..c528d191 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -24,7 +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_family_t; +typedef uint8_t psa_slh_dsa_family_t; typedef struct psa_custom_key_parameters_t { uint32_t flags; } psa_custom_key_parameters_t; @@ -311,9 +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(type) /* specification-defined value */ -#define PSA_KEY_TYPE_IS_SLH_KEY_PAIR(type) /* specification-defined value */ -#define PSA_KEY_TYPE_IS_SLH_PUBLIC_KEY(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 */ @@ -331,9 +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_GET_FAMILY(type) /* specification-defined value */ -#define PSA_KEY_TYPE_SLH_KEY_PAIR(set) /* specification-defined value */ -#define PSA_KEY_TYPE_SLH_PUBLIC_KEY(set) /* specification-defined value */ +#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 */ @@ -391,10 +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_FAMILY_SHA2_F ((psa_slh_family_t) 0x04) -#define PSA_SLH_FAMILY_SHA2_S ((psa_slh_family_t) 0x02) -#define PSA_SLH_FAMILY_SHAKE_F ((psa_slh_family_t) 0x0d) -#define PSA_SLH_FAMILY_SHAKE_S ((psa_slh_family_t) 0x0b) +#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); From 3a459077915953e1593ab1c072ed78fb01ac129a Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 26 Sep 2024 22:00:41 +0100 Subject: [PATCH 06/10] Define the key derivation procedure for SLH-DSA keys --- doc/crypto/api/keys/types.rst | 31 +++++++++++++++---------------- doc/crypto/api/ops/signature.rst | 16 ++++++++-------- 2 files changed, 23 insertions(+), 24 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index e07f3d52..77fc5354 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1234,9 +1234,9 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. param:: set A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. - The size of of an SLH-DSA key pair is the bit-size of each element in the SLH-DSA keys defined in :cite-title:`FIPS205`. + 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`. - Also see the documentation of each SLH-DSA parameter-set family for details. + See the documentation of each SLH-DSA parameter-set family for details. .. subsection:: Compatible algorithms @@ -1249,7 +1249,7 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. subsection:: Key format - A SLH-DSA key-pair is defined in :cite:`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. + 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: @@ -1261,15 +1261,13 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. subsection:: Key derivation - :issue:`TBD` + A call to `psa_key_derivation_output_key()` will draw output bytes as follows: - .. todo:: + * 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}`. - SLH-DSA key generation requires three :math:`n`\ -byte random values --- so these *could* be extracted from a suitable KDF in sequence or via separate derivation using different labels. - - However, there does not seem to be any defined standard approach. - - We could define this as permitted, but with imp-def semantics, enabling key-pair generation from a device secret, for example. + 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 */ @@ -1280,7 +1278,8 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. param:: set A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. - The 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. + 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 @@ -1293,7 +1292,7 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. subsection:: Key format - A SLH-DSA public key is defined in :cite:`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. + 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: @@ -1313,7 +1312,7 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined * SLH-DSA-SHA2-192s : ``key_bits = 192`` * SLH-DSA-SHA2-256s : ``key_bits = 256`` - They are defined in :cite-title:`FIPS205`. + They are defined in `[FIPS205]`. .. macro:: PSA_SLH_DSA_FAMILY_SHA2_F :definition: ((psa_slh_dsa_family_t) 0x04) @@ -1327,7 +1326,7 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined * SLH-DSA-SHA2-192f : ``key_bits = 192`` * SLH-DSA-SHA2-256f : ``key_bits = 256`` - They are defined in :cite:`FIPS205`. + They are defined in `[FIPS205]`. .. macro:: PSA_SLH_DSA_FAMILY_SHAKE_S :definition: ((psa_slh_dsa_family_t) 0x0b) @@ -1341,7 +1340,7 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined * SLH-DSA-SHAKE-192s : ``key_bits = 192`` * SLH-DSA-SHAKE-256s : ``key_bits = 256`` - They are defined in :cite:`FIPS205`. + They are defined in `[FIPS205]`. .. macro:: PSA_SLH_DSA_FAMILY_SHAKE_F :definition: ((psa_slh_dsa_family_t) 0x0d) @@ -1355,7 +1354,7 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined * SLH-DSA-SHAKE-192f : ``key_bits = 192`` * SLH-DSA-SHAKE-256f : ``key_bits = 256`` - They are defined in :cite:`FIPS205`. + They are defined in `[FIPS205]`. .. macro:: PSA_KEY_TYPE_IS_SLH_DSA :definition: /* specification-defined value */ diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index b147607b..f353ff2b 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -489,18 +489,18 @@ Stateless hash-based signature algorithms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The SLH-DSA signature and verification scheme is defined in :cite-title:`FIPS205`. -:cite:`FIPS205` defines twelve parameter sets which provide differing security strengths, trade-off between signature size and computation cost, and selection between SHA2 and SHAKE-based hashing. +`[FIPS205]` defines 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 :cite:`FIPS205` §9.2, Figure 17. +An SLH-DSA signature has the structure described in `[FIPS205]` §9.2, Figure 17. -See :cite:`FIPS205` §11 for details on the parameter sets, and the public key and generated signature sizes. +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`. -:cite:`FIPS205` defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. +`[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()`. * The pre-hashed signature computation generates distinct signatures to a pure signature, even with the same key and message hashing algorithm. @@ -527,7 +527,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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. + This is the pure 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. This algorithm is randomized: each invocation returns a different, equally valid signature. @@ -553,7 +553,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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`, without hedging. + 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. @@ -588,7 +588,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 :cite-title:`FIPS205`, using hedging. + 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. This algorithm is randomized: each invocation returns a different, equally valid signature. @@ -633,7 +633,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 :cite-title:`FIPS205`, without hedging. + 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. This algorithm is deterministic: each invocation with the same inputs returns an identical signature. From eaeb2f652fb0ead548b1bbe1440fa68771e5ae2b Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 26 Sep 2024 22:46:35 +0100 Subject: [PATCH 07/10] Clarify hedged/deterministic variants * Describe relaxed verification policy * Warn regarding unjustified use of deterministic variants --- doc/crypto/api/ops/signature.rst | 62 ++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 6 deletions(-) diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index f353ff2b..cf12a77a 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -503,15 +503,18 @@ The encoding of each parameter set into the key attributes is described in :secr `[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()`. -* The pre-hashed signature computation generates distinct signatures to a pure signature, even with the same key and message hashing algorithm. +* The pre-hashed signature computation --- *HashSLH-DSA* --- generates distinct signatures to a pure signature --- *SLH-DSA* ---, with the same key and message hashing algorithm. - When verifying a signature it is necessary to know which algorithm was used to generate it. + 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. -* Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every siging operation when given identical inputs. +* 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 form of algorithm can be used when verifying a 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:: 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. @@ -519,11 +522,24 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A A future version of this specification may add suitable functions and extend this algorithm to support contexts. +.. todo:: + Decide if these general comments are better kept in a common place (here), or if they should be repeated with as appropriate in each of the four algorithm definitions? + +.. rationale:: + + The use of fresh randomness, or not, when computing a signature looks primarily 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 of both SLH-DSA and HashSLH-DSA, 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. + * Some application use cases might specifically require deterministic signatures, or might require the use of hedging to mitigate possible message confidentiality threats. + .. macro:: PSA_ALG_SLH_DSA :definition: ((psa_algorithm_t) 0x06004000) .. summary:: - Stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA), using hedging. + 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. @@ -535,6 +551,11 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. note:: See the general comments in :secref:`slh-dsa-algorithms`. + 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()`. @@ -558,9 +579,18 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 `[FIPS205]` §9.2. + .. note:: See the general comments in :secref:`slh-dsa-algorithms`. + 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()`. @@ -575,7 +605,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A :definition: /* specification-defined value */ .. summary:: - Stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA), using hedging. + 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. @@ -591,11 +621,19 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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. .. note:: See the general comments in :secref:`slh-dsa-algorithms`. + 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. @@ -636,11 +674,23 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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 `[FIPS205]` §9.2. + .. note:: See the general comments in :secref:`slh-dsa-algorithms`. + 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. From 848e12212f23d0f3833094ea5b9a6ae8e6538add Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Thu, 26 Sep 2024 22:47:19 +0100 Subject: [PATCH 08/10] Update the algorithm helper macros (in line with ML-DSA) - reflecting the prehash/pure separation. --- doc/crypto/api.db/psa/crypto.h | 6 ++-- doc/crypto/api/ops/signature.rst | 39 +++++++++----------------- doc/crypto/appendix/specdef_values.rst | 17 +++++------ 3 files changed, 23 insertions(+), 39 deletions(-) diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index c528d191..545377ad 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -97,7 +97,8 @@ 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_SLH_DSA(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 */ @@ -105,6 +106,7 @@ typedef struct psa_custom_key_parameters_t { #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 */ @@ -117,9 +119,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_MAC(alg) /* specification-defined value */ #define PSA_ALG_IS_PAKE(alg) /* specification-defined value */ #define PSA_ALG_IS_PBKDF2_HMAC(alg) /* specification-defined value */ -#define PSA_ALG_IS_PURE_SLH_DSA(alg) /* specification-defined value */ #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) /* specification-defined value */ -#define PSA_ALG_IS_RANDOMIZED_SLH_DSA(alg) /* specification-defined value */ #define PSA_ALG_IS_RAW_KEY_AGREEMENT(alg) \ PSA_ALG_IS_STANDALONE_KEY_AGREEMENT(alg) #define PSA_ALG_IS_RSA_OAEP(alg) /* specification-defined value */ diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index cf12a77a..f871661c 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -707,75 +707,62 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A :definition: /* specification-defined value */ .. summary:: - Whether the specified algorithm is SLH-DSA or HashSLH-DSA. + 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 or HashSLH-DSA algorithm, ``0`` otherwise. + ``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_DETERMINISTIC_SLH_DSA +.. macro:: PSA_ALG_IS_HASH_SLH_DSA :definition: /* specification-defined value */ .. summary:: - Whether the specified algorithm is deterministic SLH-DSA or HashSLH-DSA. + 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 deterministic SLH-DSA or HashSLH-DSA algorithm, ``0`` otherwise. + ``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. - See also `PSA_ALG_IS_SLH_DSA()` and `PSA_ALG_IS_RANDOMIZED_SLH_DSA()`. - -.. macro:: PSA_ALG_IS_RANDOMIZED_SLH_DSA +.. macro:: PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA :definition: /* specification-defined value */ .. summary:: - Whether the specified algorithm is randomized SLH-DSA or HashSLH-DSA. + 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 randomized SLH-DSA or HashSLH-DSA algorithm, ``0`` otherwise. + ``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_SLH_DSA()` and `PSA_ALG_IS_DETERMINISTIC_SLH_DSA()`. + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_HEDGED_HASH_SLH_DSA()`. -.. macro:: PSA_ALG_IS_PURE_SLH_DSA +.. macro:: PSA_ALG_IS_HEDGED_HASH_SLH_DSA :definition: /* specification-defined value */ .. summary:: - Whether the specified algorithm is pure SLH-DSA. + 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 pure SLH-DSA algorithm, ``0`` otherwise. + ``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. -.. 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. + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA()`. - This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. Asymmetric signature functions ------------------------------ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index 324ad75e..71d165d1 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -84,8 +84,8 @@ Algorithm macros #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000700) - #define PSA_ALG_IS_DETERMINISTIC_SLH_DSA(alg) \ - (((alg) & ~0x000002ff) == 0x06004100) + #define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004300) #define PSA_ALG_IS_ECDH(alg) \ (((alg) & 0x7fff0000) == 0x09020000) @@ -110,6 +110,9 @@ Algorithm macros #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) @@ -143,15 +146,9 @@ Algorithm macros #define PSA_ALG_IS_PBKDF2_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08800100) - #define PSA_ALG_IS_PURE_SLH_DSA(alg) \ - (((alg) & ~0x000001ff) == 0x06004000) - #define PSA_ALG_IS_RANDOMIZED_ECDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000600) - #define PSA_ALG_IS_RANDOMIZED_SLH_DSA(alg) \ - (((alg) & ~0x000002ff) == 0x06004000) - #define PSA_ALG_IS_RSA_OAEP(alg) \ (((alg) & ~0x000000ff) == 0x07000300) @@ -172,14 +169,14 @@ Algorithm macros #define PSA_ALG_IS_SIGN_HASH(alg) \ (PSA_ALG_IS_SIGN(alg) && \ - (alg) != PSA_ALG_PURE_EDDSA && !PSA_ALG_IS_PURE_SLH_DSA(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) & ~0x000003ff) == 0x06004000) + (((alg) & ~0x00000100) == 0x06004000) #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08000700) From bf429b49cfafb4952aa598af4c543f52c15a5495 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 4 Oct 2024 17:18:20 +0100 Subject: [PATCH 09/10] Update SLH-DSA with notes and warnings, aligned with ML-DSA PR --- doc/crypto/api/keys/types.rst | 16 +++++++ doc/crypto/api/ops/signature.rst | 71 +++++++++++++++++--------------- doc/crypto/references | 6 +++ 3 files changed, 60 insertions(+), 33 deletions(-) diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 77fc5354..ea11c788 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1249,6 +1249,14 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. 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: @@ -1292,6 +1300,14 @@ The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined .. 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: diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index f871661c..bd24d03c 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -485,11 +485,11 @@ Elliptic curve signature algorithms .. _slh-dsa-algorithms: -Stateless hash-based signature algorithms +Stateless Hash-based signature algorithms ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ The SLH-DSA signature and verification scheme is defined in :cite-title:`FIPS205`. -`[FIPS205]` defines 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 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. @@ -503,37 +503,52 @@ The encoding of each parameter set into the key attributes is described in :secr `[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()`. -* The pre-hashed signature computation --- *HashSLH-DSA* --- generates distinct signatures to a pure signature --- *SLH-DSA* ---, with the same key and message hashing algorithm. +.. _slh-dsa-deterministic-signatures: - 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:: 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. +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. +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. +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:: - 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. + 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. -.. todo:: - Decide if these general comments are better kept in a common place (here), or if they should be repeated with as appropriate in each of the four algorithm definitions? +.. 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 looks primarily like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in `[FIPS205]`. + 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 of both SLH-DSA and HashSLH-DSA, for the following reasons: + 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. - * Some application use cases might specifically require deterministic signatures, or might require the use of hedging to mitigate possible message confidentiality threats. + * 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) @@ -543,13 +558,11 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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]`, using hedging. + 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. - - .. note:: - See the general comments in :secref:`slh-dsa-algorithms`. + See the `notes on hedged signatures `_. When `PSA_ALG_SLH_DSA` is used as a permitted algorithm in a key policy, this permits: @@ -581,10 +594,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. warning:: It is recommended to use the hedged `PSA_ALG_SLH_DSA` algorithm instead, when supported by the implementation. - See `[FIPS205]` §9.2. - - .. note:: - See the general comments in :secref:`slh-dsa-algorithms`. + See the `notes on deterministic signatures `_. When `PSA_ALG_DETERMINISTIC_SLH_DSA` is used as a permitted algorithm in a key policy, this permits: @@ -625,9 +635,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A 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. - - .. note:: - See the general comments in :secref:`slh-dsa-algorithms`. + See the `notes on hedged signatures `_. When `PSA_ALG_HASH_SLH_DSA()` is used as a permitted algorithm in a key policy, this permits: @@ -681,10 +689,7 @@ Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_A .. warning:: It is recommended to use the hedged `PSA_ALG_HASH_SLH_DSA()` algorithm instead, when supported by the implementation. - See `[FIPS205]` §9.2. - - .. note:: - See the general comments in :secref:`slh-dsa-algorithms`. + 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: diff --git a/doc/crypto/references b/doc/crypto/references index 1c1acab6..bb4b049d 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -402,3 +402,9 @@ :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 01) + :author: IETF + :publication: July 2024 (DRAFT) + :url: datatracker.ietf.org/doc/draft-ietf-lamps-x509-slhdsa-01 From 96f89d5a9775a980bef9a2672c468c360cb40a7c Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Tue, 15 Oct 2024 09:15:45 +0100 Subject: [PATCH 10/10] Updated reference to draft 2 of the IETF LAMPS specification for SLH-DSA --- doc/crypto/references | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/crypto/references b/doc/crypto/references index bb4b049d..84425b10 100644 --- a/doc/crypto/references +++ b/doc/crypto/references @@ -404,7 +404,7 @@ :url: doi.org/10.6028/NIST.FIPS.205 .. reference:: LAMPS-SLHDSA - :title: Internet X.509 Public Key Infrastructure: Algorithm Identifiers for SLH-DSA (Draft 01) + :title: Internet X.509 Public Key Infrastructure: Algorithm Identifiers for SLH-DSA (Draft 02) :author: IETF - :publication: July 2024 (DRAFT) - :url: datatracker.ietf.org/doc/draft-ietf-lamps-x509-slhdsa-01 + :publication: October 2024 (DRAFT) + :url: datatracker.ietf.org/doc/draft-ietf-lamps-x509-slhdsa-02