From 5e92133cbd1c0f745696a4cd6b3fea4e79b3a8f4 Mon Sep 17 00:00:00 2001 From: Andrew Thoelke Date: Fri, 30 Jan 2026 16:41:27 +0000 Subject: [PATCH] Integrate the PQC Extension into the Crypto API specification --- doc/crypto/about/references | 77 ++ doc/crypto/api.db/psa/crypto.h | 56 +- doc/crypto/api/keys/types.rst | 600 ++++++++++++- doc/crypto/api/ops/algorithms.rst | 38 +- doc/crypto/api/ops/hash.rst | 60 +- doc/crypto/api/ops/key-encapsulation.rst | 45 +- doc/crypto/api/ops/signature.rst | 836 ++++++++++++++++++ doc/crypto/api/ops/xof.rst | 10 +- doc/crypto/appendix/encodings.rst | 60 +- doc/crypto/appendix/history.rst | 11 +- doc/crypto/appendix/specdef_values.rst | 70 +- doc/crypto/conf.py | 4 +- doc/crypto/figure/encoding/slh_dsa_key.json | 18 + .../figure/encoding/slh_dsa_key.json.license | 2 + doc/crypto/figure/encoding/slh_dsa_key.pdf | Bin 0 -> 6866 bytes .../figure/encoding/slh_dsa_key.pdf.license | 2 + doc/crypto/figure/encoding/slh_dsa_key.svg | 2 + .../figure/encoding/slh_dsa_key.svg.license | 2 + doc/crypto/overview/intro.rst | 6 +- doc/crypto/substitutions | 1 + 20 files changed, 1854 insertions(+), 46 deletions(-) create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.json create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.json.license create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.pdf create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.pdf.license create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.svg create mode 100644 doc/crypto/figure/encoding/slh_dsa_key.svg.license create mode 100644 doc/crypto/substitutions diff --git a/doc/crypto/about/references b/doc/crypto/about/references index 5f0b6a45..534ec909 100644 --- a/doc/crypto/about/references +++ b/doc/crypto/about/references @@ -462,3 +462,80 @@ :publication: November 2024 :url: tools.ietf.org/html/rfc9688.html +.. reference:: FIPS203 + :title: FIPS Publication 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.203 + +.. reference:: FIPS204 + :title: FIPS Publication 204: Module-Lattice-Based Digital Signature Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.204 + +.. reference:: FIPS205 + :title: FIPS Publication 205: Stateless Hash-Based Digital Signature Standard + :author: NIST + :publication: August 2024 + :url: doi.org/10.6028/NIST.FIPS.205 + +.. reference:: LAMPS-MLKEM + :title: Internet X.509 Public Key Infrastructure - Algorithm Identifiers for Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) + :author: IETF + :publication: July 2025 (Draft 11) + :url: datatracker.ietf.org/doc/html/draft-ietf-lamps-kyber-certificates-11 + +.. reference:: RFC9881 + :title: Internet X.509 Public Key Infrastructure --- Algorithm Identifiers for the Module-Lattice-Based Digital Signature Algorithm (ML-DSA) + :author: IETF + :publication: October 2025 + :url: tools.ietf.org/html/rfc9881 + +.. reference:: RFC9909 + :title: Internet X.509 Public Key Infrastructure --- Algorithm Identifiers for the Stateless Hash-Based Digital Signature Algorithm (SLH-DSA) + :author: IETF + :publication: December 2025 + :url: tools.ietf.org/html/rfc9909 + +.. reference:: NIST-PQC + :title: Post-Quantum Cryptography + :author: NIST + :publication: PQC Project page + :url: nist.gov/pqcrypto + +.. reference:: SP800-208 + :title: NIST Special Publication 800-208: Recommendation for Stateful Hash-Based Signature Schemes + :author: NIST + :publication: October 2020 + :url: doi.org/10.6028/NIST.SP.800-208 + +.. reference:: RFC8391 + :title: XMSS: eXtended Merkle Signature Scheme + :author: IRTF + :publication: May 2018 + :url: tools.ietf.org/html/rfc8391 + +.. reference:: RFC8554 + :title: Leighton-Micali Hash-Based Signatures + :author: IRTF + :publication: April 2019 + :url: tools.ietf.org/html/rfc8554 + +.. reference:: RFC9858 + :title: Additional Parameter sets for HSS/LMS Hash-Based Signatures + :author: IRTF + :publication: October 2025 + :url: tools.ietf.org/html/rfc9858 + +.. reference:: RFC9802 + :title: Use of the HSS and XMSS Hash-Based Signature Algorithms in Internet X.509 Public Key Infrastructure + :author: IETF + :publication: June 2025 + :url: tools.ietf.org/html/rfc9802 + +.. reference:: RFC8702 + :title: Use of the SHAKE One-Way Hash Functions in the Cryptographic Message Syntax (CMS) + :author: IETF + :publication: January 2020 + :url: tools.ietf.org/html/rfc8702.html diff --git a/doc/crypto/api.db/psa/crypto.h b/doc/crypto/api.db/psa/crypto.h index fc17def6..f52c2b87 100644 --- a/doc/crypto/api.db/psa/crypto.h +++ b/doc/crypto/api.db/psa/crypto.h @@ -1,4 +1,4 @@ -// SPDX-FileCopyrightText: Copyright 2018-2025 Arm Limited and/or its affiliates +// SPDX-FileCopyrightText: Copyright 2018-2026 Arm Limited and/or its affiliates // SPDX-License-Identifier: Apache-2.0 typedef /* implementation-defined type */ psa_aead_operation_t; @@ -24,6 +24,7 @@ typedef uint32_t psa_pake_primitive_t; typedef uint8_t psa_pake_primitive_type_t; typedef uint8_t psa_pake_role_t; typedef uint8_t psa_pake_step_t; +typedef uint8_t psa_slh_dsa_family_t; typedef /* implementation-defined type */ psa_xof_operation_t; typedef struct psa_custom_key_parameters_t { uint32_t flags; @@ -77,6 +78,12 @@ 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_ML_DSA(hash_alg) \ + /* specification-defined value */ +#define PSA_ALG_DETERMINISTIC_HASH_SLH_DSA(hash_alg) \ + /* specification-defined value */ +#define PSA_ALG_DETERMINISTIC_ML_DSA ((psa_algorithm_t) 0x06004500) +#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 */ @@ -89,22 +96,33 @@ 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_ML_DSA(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 */ #define PSA_ALG_HMAC(hash_alg) /* specification-defined value */ +#define PSA_ALG_HSS ((psa_algorithm_t) 0x06004900) #define PSA_ALG_IS_AEAD(alg) /* specification-defined value */ #define PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER(alg) /* specification-defined value */ #define PSA_ALG_IS_ASYMMETRIC_ENCRYPTION(alg) /* specification-defined value */ #define PSA_ALG_IS_BLOCK_CIPHER_MAC(alg) /* specification-defined value */ #define PSA_ALG_IS_CIPHER(alg) /* specification-defined value */ #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_DETERMINISTIC_HASH_ML_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 */ #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_ML_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HASH_SLH_DSA(alg) /* specification-defined value */ +#define PSA_ALG_IS_HEDGED_HASH_ML_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,6 +135,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_IS_KEY_ENCAPSULATION(alg) /* specification-defined value */ #define PSA_ALG_IS_KEY_WRAP(alg) /* specification-defined value */ #define PSA_ALG_IS_MAC(alg) /* specification-defined value */ +#define PSA_ALG_IS_ML_DSA(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_RANDOMIZED_ECDSA(alg) /* specification-defined value */ @@ -130,6 +149,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 */ @@ -153,9 +173,12 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_KEY_AGREEMENT_GET_KDF(alg) /* specification-defined value */ #define PSA_ALG_KW ((psa_algorithm_t)0x0B400100) #define PSA_ALG_KWP ((psa_algorithm_t)0x0BC00200) +#define PSA_ALG_LMS ((psa_algorithm_t) 0x06004800) #define PSA_ALG_MD2 ((psa_algorithm_t)0x02000001) #define PSA_ALG_MD4 ((psa_algorithm_t)0x02000002) #define PSA_ALG_MD5 ((psa_algorithm_t)0x02000003) +#define PSA_ALG_ML_DSA ((psa_algorithm_t) 0x06004400) +#define PSA_ALG_ML_KEM ((psa_algorithm_t)0x0c000200) #define PSA_ALG_NONE ((psa_algorithm_t)0) #define PSA_ALG_OFB ((psa_algorithm_t)0x04c01200) #define PSA_ALG_PBKDF2_AES_CMAC_PRF_128 ((psa_algorithm_t)0x08800200) @@ -173,16 +196,21 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_SHA3_384 ((psa_algorithm_t)0x02000012) #define PSA_ALG_SHA3_512 ((psa_algorithm_t)0x02000013) #define PSA_ALG_SHAKE128 ((psa_algorithm_t)0x0D000100) +#define PSA_ALG_SHAKE128_256 ((psa_algorithm_t)0x02000016) #define PSA_ALG_SHAKE256 ((psa_algorithm_t)0x0D000200) +#define PSA_ALG_SHAKE256_192 ((psa_algorithm_t)0x02000017) +#define PSA_ALG_SHAKE256_256 ((psa_algorithm_t)0x02000018) #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) #define PSA_ALG_SHA_256 ((psa_algorithm_t)0x02000009) +#define PSA_ALG_SHA_256_192 ((psa_algorithm_t)0x0200000E) #define PSA_ALG_SHA_384 ((psa_algorithm_t)0x0200000a) #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_SIGN_SUPPORTS_CONTEXT(alg) /* implementation-defined value */ +#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) \ @@ -201,6 +229,8 @@ typedef struct psa_custom_key_parameters_t { #define PSA_ALG_WPA3_SAE_GDH(hash_alg) /* specification-defined value */ #define PSA_ALG_WPA3_SAE_H2E(hash_alg) /* specification-defined value */ #define PSA_ALG_XCHACHA20_POLY1305 ((psa_algorithm_t)0x05100600) +#define PSA_ALG_XMSS ((psa_algorithm_t) 0x06004A00) +#define PSA_ALG_XMSS_MT ((psa_algorithm_t) 0x06004B00) #define PSA_ALG_XOF_HAS_CONTEXT(alg) /* specification-defined value */ #define PSA_ALG_XTS ((psa_algorithm_t)0x0440ff00) #define PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE \ @@ -232,7 +262,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_CIPHER_UPDATE_OUTPUT_SIZE(key_type, alg, input_length) \ /* implementation-defined value */ #define PSA_CRYPTO_API_VERSION_MAJOR 1 -#define PSA_CRYPTO_API_VERSION_MINOR 4 +#define PSA_CRYPTO_API_VERSION_MINOR 5 #define PSA_CUSTOM_KEY_PARAMETERS_INIT { 0 } #define PSA_DH_FAMILY_RFC3526 ((psa_dh_family_t) 0x05) #define PSA_DH_FAMILY_RFC7919 ((psa_dh_family_t) 0x03) @@ -318,6 +348,7 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_ECC_KEY_PAIR(curve) /* specification-defined value */ #define PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) /* specification-defined value */ #define PSA_KEY_TYPE_HMAC ((psa_key_type_t)0x1100) +#define PSA_KEY_TYPE_HSS_PUBLIC_KEY ((psa_key_type_t)0x4008) #define PSA_KEY_TYPE_IS_ASYMMETRIC(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_DH(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_DH_KEY_PAIR(type) /* specification-defined value */ @@ -326,8 +357,15 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_IS_ECC_KEY_PAIR(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_KEY_PAIR(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_ML_DSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_ML_KEM(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_RSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA(type) /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ + /* specification-defined value */ +#define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ + /* specification-defined value */ #define PSA_KEY_TYPE_IS_SPAKE2P(type) /* specification-defined value */ #define PSA_KEY_TYPE_IS_SPAKE2P_KEY_PAIR(type) \ /* specification-defined value */ @@ -338,6 +376,11 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_IS_WPA3_SAE_ECC(type) /* specification-defined value */ #define PSA_KEY_TYPE_KEY_PAIR_OF_PUBLIC_KEY(type) \ /* specification-defined value */ +#define PSA_KEY_TYPE_LMS_PUBLIC_KEY ((psa_key_type_t)0x4007) +#define PSA_KEY_TYPE_ML_DSA_KEY_PAIR ((psa_key_type_t)0x7002) +#define PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY ((psa_key_type_t)0x4002) +#define PSA_KEY_TYPE_ML_KEM_KEY_PAIR ((psa_key_type_t)0x7004) +#define PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY ((psa_key_type_t)0x4004) #define PSA_KEY_TYPE_NONE ((psa_key_type_t)0x0000) #define PSA_KEY_TYPE_PASSWORD ((psa_key_type_t)0x1203) #define PSA_KEY_TYPE_PASSWORD_HASH ((psa_key_type_t)0x1205) @@ -347,6 +390,9 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_RAW_DATA ((psa_key_type_t)0x1001) #define PSA_KEY_TYPE_RSA_KEY_PAIR ((psa_key_type_t)0x7001) #define PSA_KEY_TYPE_RSA_PUBLIC_KEY ((psa_key_type_t)0x4001) +#define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) /* specification-defined value */ +#define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) /* specification-defined value */ #define PSA_KEY_TYPE_SM4 ((psa_key_type_t)0x2405) #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) /* specification-defined value */ #define PSA_KEY_TYPE_SPAKE2P_KEY_PAIR(curve) /* specification-defined value */ @@ -359,6 +405,8 @@ typedef struct psa_custom_key_parameters_t { #define PSA_KEY_TYPE_WPA3_SAE_ECC_GET_FAMILY(type) \ /* specification-defined value */ #define PSA_KEY_TYPE_XCHACHA20 ((psa_key_type_t)0x2007) +#define PSA_KEY_TYPE_XMSS_MT_PUBLIC_KEY ((psa_key_type_t)0x400D) +#define PSA_KEY_TYPE_XMSS_PUBLIC_KEY ((psa_key_type_t)0x400B) #define PSA_KEY_USAGE_CACHE ((psa_key_usage_t)0x00000004) #define PSA_KEY_USAGE_COPY ((psa_key_usage_t)0x00000002) #define PSA_KEY_USAGE_DECRYPT ((psa_key_usage_t)0x00000200) @@ -417,6 +465,10 @@ typedef struct psa_custom_key_parameters_t { #define PSA_SIGNATURE_MAX_SIZE /* implementation-defined value */ #define PSA_SIGN_OUTPUT_SIZE(key_type, key_bits, alg) \ /* implementation-defined value */ +#define PSA_SLH_DSA_FAMILY_SHA2_F ((psa_slh_dsa_family_t) 0x04) +#define PSA_SLH_DSA_FAMILY_SHA2_S ((psa_slh_dsa_family_t) 0x02) +#define PSA_SLH_DSA_FAMILY_SHAKE_F ((psa_slh_dsa_family_t) 0x0d) +#define PSA_SLH_DSA_FAMILY_SHAKE_S ((psa_slh_dsa_family_t) 0x0b) #define PSA_TLS12_ECJPAKE_TO_PMS_OUTPUT_SIZE 32 #define PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE /* implementation-defined value */ #define PSA_WRAP_KEY_OUTPUT_SIZE(wrap_key_type, alg, key_type, key_bits) \ diff --git a/doc/crypto/api/keys/types.rst b/doc/crypto/api/keys/types.rst index 902060aa..fb6ecdfb 100644 --- a/doc/crypto/api/keys/types.rst +++ b/doc/crypto/api/keys/types.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2026 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -1170,10 +1170,15 @@ The other is a public key, which is meant to be shared with other participants i The |API| defines the following types of asymmetric key: -* :secref:`rsa-keys` -* :secref:`ecc-keys` -* :secref:`dh-keys` -* :secref:`spake2p-keys` +* :secref:`rsa-keys` +* :secref:`ecc-keys` +* :secref:`dh-keys` +* :secref:`lms-keys` +* :secref:`xmss-keys` +* :secref:`ml-dsa-keys` +* :secref:`slh-dsa-keys` +* :secref:`ml-kem-keys` +* :secref:`spake2p-keys` In the |API|, key objects can either be a key pair, providing both the private and public key, or just a public key. The difference in the key type values for a key pair and a public key for the same scheme is common across all asymmetric keys. @@ -1681,6 +1686,591 @@ Diffie Hellman keys .. return:: psa_dh_family_t The finite field Diffie-Hellman group family id, if ``type`` is a supported finite field Diffie-Hellman key. Unspecified if ``type`` is not a supported finite field Diffie-Hellman key. +.. _lms-keys: + +Leighton-Micali Signature keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. macro:: PSA_KEY_TYPE_LMS_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4007) + + .. summary:: + Leighton-Micali Signatures (LMS) public key. + + .. versionadded:: 1.3 + + The parameterization of an LMS key is fully encoded in the key data. + + The bit size used in the attributes of an LMS public key is output length, in bits, of the hash function identified by the LMS parameter set. + + * SHA-256/192, SHAKE256/192 : ``key_bits = 192`` + * SHA-256, SHAKE256/256 : ``key_bits = 256`` + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_LMS` + + .. subsection:: Key format + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is the encoded ``lms_public_key`` structure, defined in :rfc:`8554#3`. + +.. macro:: PSA_KEY_TYPE_HSS_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4008) + + .. summary:: + Hierarchical Signature Scheme (HSS) public key. + + .. versionadded:: 1.3 + + The parameterization of an HSS key is fully encoded in the key data. + + The bit size used in the attributes of an HSS public key is output length, in bits, of the hash function identified by the HSS parameter set. + + * SHA-256/192, SHAKE256/192 : ``key_bits = 192`` + * SHA-256, SHAKE256/256 : ``key_bits = 256`` + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_HSS` + + .. subsection:: Key format + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is the encoded ``hss_public_key`` structure, defined in :rfc:`8554#3`. + + .. rationale:: + + This format is the same as that specified for X.509 in :rfc-title:`9802`. + +.. _xmss-keys: + +XMSS and |XMSS^MT| keys +~~~~~~~~~~~~~~~~~~~~~~~ + +.. macro:: PSA_KEY_TYPE_XMSS_PUBLIC_KEY + :definition: ((psa_key_type_t)0x400B) + + .. summary:: + eXtended Merkle Signature Scheme (XMSS) public key. + + .. versionadded:: 1.3 + + The parameterization of an XMSS key is fully encoded in the key data. + + The bit size used in the attributes of an XMSS public key is output length, in bits, of the hash function identified by the XMSS parameter set. + + * SHA-256/192, SHAKE256/192 : ``key_bits = 192`` + * SHA-256, SHAKE256/256 : ``key_bits = 256`` + + .. note:: + For a multi-tree XMSS key, see `PSA_KEY_TYPE_XMSS_MT_PUBLIC_KEY`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_XMSS` + + .. subsection:: Key format + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is the encoded ``xmss_public_key`` structure, defined in :rfc:`8391#B.3`. + + .. rationale:: + + This format is the same as that specified for X.509 in :rfc-title:`9802`. + +.. macro:: PSA_KEY_TYPE_XMSS_MT_PUBLIC_KEY + :definition: ((psa_key_type_t)0x400D) + + .. summary:: + Multi-tree eXtended Merkle Signature Scheme (|XMSS^MT|) public key. + + .. versionadded:: 1.3 + + The parameterization of an |XMSS^MT| key is fully encoded in the key data. + + The bit size used in the attributes of an |XMSS^MT| public key is output length, in bits, of the hash function identified by the |XMSS^MT| parameter set. + + * SHA-256/192, SHAKE256/192 : ``key_bits = 192`` + * SHA-256, SHAKE256/256 : ``key_bits = 256`` + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_XMSS_MT` + + .. subsection:: Key format + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is the encoded ``xmssmt_public_key`` structure, defined in :rfc:`8391#C.3`. + + .. rationale:: + + This format is the same as that specified for X.509 in :rfc-title:`9802`. + +.. _ml-dsa-keys: + +Module Lattice-based signature keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The |API| supports Module Lattice-based digital signatures (ML-DSA), as defined in :cite-title:`FIPS204`. + +.. macro:: PSA_KEY_TYPE_ML_DSA_KEY_PAIR + :definition: ((psa_key_type_t)0x7002) + + .. summary:: + ML-DSA key pair: both the private and public key. + + .. versionadded:: 1.3 + + The bit size used in the attributes of an ML-DSA key is a measure of the security strength of the ML-DSA parameter set in `[FIPS204]`: + + * ML-DSA-44 : ``key_bits = 128`` + * ML-DSA-65 : ``key_bits = 192`` + * ML-DSA-87 : ``key_bits = 256`` + + See also §4 in `[FIPS204]`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_DSA` + * `PSA_ALG_HASH_ML_DSA` + * `PSA_ALG_DETERMINISTIC_ML_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` + + .. subsection:: Key format + + An ML-DSA key pair is the :math:`(pk,sk)` pair of public key and secret key, which are generated from a secret 32-byte seed, :math:`\xi`. See `[FIPS204]` §5.1. + + In calls to :code:`psa_import_key()` and :code:`psa_export_key()`, the key-pair data format is the 32-byte seed :math:`\xi`. + + .. rationale:: + + The formats for X.509 handling of ML-DSA keys are specified in :rfc-title:`9881`. + This permits a choice of three formats for the decapsulation key material, incorporating one, or both, of the seed value :math:`\xi` and the expanded secret key :math:`sk`. + + The |API| only supports the recommended format from :rfc:`9881`, which is the bytes of the seed :math:`\xi`, but without the ASN.1 encoding prefix. + This suits the constrained nature of |API| implementations, where interoperation with expanded secret-key formats is not required. + + See `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` for the data format used when exporting the public key with :code:`psa_export_public_key()`. + + .. admonition:: Implementation note + + An implementation can optionally compute and store the :math:`(pk,sk)` values, to accelerate operations that use the key. + It is recommended that an implementation retains the seed :math:`\xi` with the key pair, in order to export the key, or copy the key to a different location. + + .. subsection:: Key derivation + + A call to :code:`psa_key_derivation_output_key()` will draw 32 bytes of output and use these as the 32-byte ML-DSA key-pair seed, :math:`\xi`. + The key pair :math:`(pk, sk)` is generated from the seed as defined by ``ML-DSA.KeyGen_internal()`` in `[FIPS204]` §6.1. + + .. admonition:: Implementation note + + It is :an implementation choice whether the seed :math:`\xi` is expanded to :math:`(pk, sk)` at the point of derivation, or only just before the key is used. + +.. macro:: PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4002) + + .. summary:: + ML-DSA public key. + + .. versionadded:: 1.3 + + The bit size used in the attributes of an ML-DSA public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ML_DSA_KEY_PAIR`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_DSA` + * `PSA_ALG_HASH_ML_DSA` + * `PSA_ALG_DETERMINISTIC_ML_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` + + .. subsection:: Key format + + An ML-DSA public key is the :math:`pk` output of ``ML-DSA.KeyGen()``, defined in `[FIPS204]` §5.1. + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is :math:`pk`. + + .. rationale:: + + This format is the same as that specified for X.509 in :rfc-title:`9881`. + + The size of the public key depends on the ML-DSA parameter set as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Public-key size in bytes + ML-DSA-44, 1312 + ML-DSA-65, 1952 + ML-DSA-87, 2592 + +.. macro:: PSA_KEY_TYPE_IS_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-DSA key, either a key pair or a public key. + + .. versionadded:: 1.3 + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. _slh-dsa-keys: + +Stateless Hash-based signature keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The |API| supports Stateless Hash-based digital signatures (SLH-DSA), as defined in :cite-title:`FIPS205`. + +.. typedef:: uint8_t psa_slh_dsa_family_t + + .. summary:: + The type of identifiers of a Stateless hash-based DSA parameter set. + + .. versionadded:: 1.3 + + The parameter-set identifier is required to create an SLH-DSA key using the `PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` or `PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` macros. + + The specific SLH-DSA parameter set within a family is identified by the ``key_bits`` attribute of the key. + + The range of SLH-DSA family identifier values is divided as follows: + + :code:`0x00` + Reserved. + Not allocated to an SLH-DSA parameter-set family. + :code:`0x01 - 0x7f` + SLH-DSA parameter-set family identifiers defined by this standard. + Unallocated values in this range are reserved for future use. + :code:`0x80 - 0xff` + Invalid. + Values in this range must not be used. + + The least significant bit of an SLH-DSA family identifier is a parity bit for the whole key type. + See :secref:`slh-dsa-key-encoding` for details of the encoding of asymmetric key types. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + SLH-DSA key pair: both the private key and public key. + + .. versionadded:: 1.3 + + .. param:: set + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. + + The bit size used in the attributes of an SLH-DSA key pair is the bit-size of each component in the SLH-DSA keys defined in `[FIPS205]`. + That is, for a parameter set with security parameter :math:`n`, the bit-size in the key attributes is :math:`8n`. + See the documentation of each SLH-DSA parameter-set family for details. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_SLH_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + + .. subsection:: Key format + + 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. + + In calls to :code:`psa_import_key()` and :code:`psa_export_key()`, the key-pair data format is the concatenation of the four octet strings: + + .. math:: + + SK\text{.seed}\ ||\ SK\text{.prf}\ ||\ PK\text{.seed}\ ||\ PK\text{.root} + + .. rationale:: + + This format is the same as that specified for X.509 in :rfc-title:`9909`. + + See `PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY` for the data format used when exporting the public key with :code:`psa_export_public_key()`. + + .. subsection:: Key derivation + + A call to :code:`psa_key_derivation_output_key()` will draw output bytes as follows: + + * :math:`n` bytes are drawn as :math:`SK\text{.seed}`. + * :math:`n` bytes are drawn as :math:`SK\text{.prf}`. + * :math:`n` bytes are drawn as :math:`PK\text{.seed}`. + + Here, :math:`n` is the security parameter for the selected SLH-DSA parameter set. + + The private key :math:`(SK\text{.seed},SK\text{.prf},PK\text{.seed},PK\text{.root})` is generated from these values as defined by ``slh_keygen_internal()`` in `[FIPS205]` §9.1. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + SLH-DSA public key. + + .. versionadded:: 1.3 + + .. param:: set + A value of type `psa_slh_dsa_family_t` that identifies the SLH-DSA parameter-set family to be used. + + The bit size used in the attributes of an SLH-DSA public key is the same as the corresponding private key. + See `PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` and the documentation of each SLH-DSA parameter-set family for details. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_SLH_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + + .. subsection:: Key format + + 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. + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is the concatenation of the two octet strings: + + .. math:: + + PK\text{.seed}\ ||\ PK\text{.root} + + .. rationale:: + + This format is the same as that specified for X.509 in :rfc-title:`9909`. + +.. 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. + + .. versionadded:: 1.3 + + This family comprises the following parameter sets: + + * SLH-DSA-SHA2-128s : ``key_bits = 128`` + * SLH-DSA-SHA2-192s : ``key_bits = 192`` + * SLH-DSA-SHA2-256s : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHA2_F + :definition: ((psa_slh_dsa_family_t) 0x04) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHA2-\ *NNN*\ f parameter sets. + + .. versionadded:: 1.3 + + This family comprises the following parameter sets: + + * SLH-DSA-SHA2-128f : ``key_bits = 128`` + * SLH-DSA-SHA2-192f : ``key_bits = 192`` + * SLH-DSA-SHA2-256f : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHAKE_S + :definition: ((psa_slh_dsa_family_t) 0x0b) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHAKE-\ *NNN*\ s parameter sets. + + .. versionadded:: 1.3 + + This family comprises the following parameter sets: + + * SLH-DSA-SHAKE-128s : ``key_bits = 128`` + * SLH-DSA-SHAKE-192s : ``key_bits = 192`` + * SLH-DSA-SHAKE-256s : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_SLH_DSA_FAMILY_SHAKE_F + :definition: ((psa_slh_dsa_family_t) 0x0d) + + .. summary:: + SLH-DSA family for the SLH-DSA-SHAKE-\ *NNN*\ f parameter sets. + + .. versionadded:: 1.3 + + This family comprises the following parameter sets: + + * SLH-DSA-SHAKE-128f : ``key_bits = 128`` + * SLH-DSA-SHAKE-192f : ``key_bits = 192`` + * SLH-DSA-SHAKE-256f : ``key_bits = 256`` + + They are defined in `[FIPS205]`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA key, either a key pair or a public key. + + .. versionadded:: 1.3 + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA key pair. + + .. versionadded:: 1.3 + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an SLH-DSA public key. + + .. versionadded:: 1.3 + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. + +.. macro:: PSA_KEY_TYPE_SLH_DSA_GET_FAMILY + :definition: /* specification-defined value */ + + .. summary:: + Extract the parameter-set family from an SLH-DSA key type. + + .. versionadded:: 1.3 + + .. param:: type + An SLH-DSA key type: a value of type :code:`psa_key_type_t` such that :code:`PSA_KEY_TYPE_IS_SLH_DSA(type)` is true. + + .. return:: psa_dh_family_t + The SLH-DSA parameter-set family id, if ``type`` is a supported SLH-DSA key. Unspecified if ``type`` is not a supported SLH-DSA key. + +.. _ml-kem-keys: + +Module Lattice-based key-encapsulation keys +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The |API| supports Module Lattice-based key encapsulation (ML-KEM) as defined in :cite-title:`FIPS203`. + +.. macro:: PSA_KEY_TYPE_ML_KEM_KEY_PAIR + :definition: ((psa_key_type_t)0x7004) + + .. summary:: + ML-KEM key pair: both the decapsulation and encapsulation key. + + .. versionadded:: 1.3 + + The |API| treats decapsulation keys as private keys and encapsulation keys as public keys. + + The bit size used in the attributes of an ML-KEM key is specified by the numeric part of the parameter-set identifier defined in `[FIPS203]`. + The parameter-set identifier refers to the key strength, and not to the actual size of the key. + The following values for the ``key_bits`` key attribute are used to select a specific ML-KEM parameter set: + + * ML-KEM-512 : ``key_bits = 512`` + * ML-KEM-768 : ``key_bits = 768`` + * ML-KEM-1024 : ``key_bits = 1024`` + + See also §8 in `[FIPS203]`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_KEM` + + .. subsection:: Key format + + An ML-KEM key pair is the :math:`(ek,dk)` pair of encapsulation key and decapsulation key, which are generated from two secret 32-byte seeds, :math:`d` and :math:`z`. See `[FIPS203]` §7.1. + + In calls to :code:`psa_import_key()` and :code:`psa_export_key()`, the key-pair data format is the concatenation of the two seed values: :math:`d\ ||\ z`. + + .. rationale:: + + The formats for X.509 handling of ML-KEM keys are specified in :cite-title:`LAMPS-MLKEM`. + This permits a choice of three formats for the decapsulation key material, incorporating one, or both, of the seed values :math:`d\ ||\ z` and the expanded decapsulation key :math:`dk`. + + The |API| only supports the recommended format from `[LAMPS-MLKEM]`, which is the concatenated bytes of the seed values :math:`d\ ||\ z`, but without the ASN.1 encoding prefix. + This suits the constrained nature of |API| implementations, where interoperation with expanded decapsulation-key formats is not required. + + See `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY` for the data format used when exporting the public key with :code:`psa_export_public_key()`. + + .. admonition:: Implementation note + + An implementation can optionally compute and store the :math:`dk` value, which also contains the encapsulation key :math:`ek`, to accelerate operations that use the key. + It is recommended that an implementation retains the seed pair :math:`(d,z)` with the decapsulation key, in order to export the key, or copy the key to a different location. + + .. subsection:: Key derivation + + A call to :code:`psa_key_derivation_output_key()` will construct an ML-KEM key pair using the following process: + + 1. Draw 32 bytes of output as the seed value :math:`d`. + #. Draw 32 bytes of output as the seed value :math:`z`. + + The key pair :math:`(ek,dk)` is generated from the seed as defined by ``ML-KEM.KeyGen_internal()`` in `[FIPS203]` §6.1. + + .. admonition:: Implementation note + + It is an implementation choice whether the seed-pair :math:`(d,z)` is expanded to :math:`(ek,dk)` at the point of derivation, or only just before the key is used. + +.. macro:: PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY + :definition: ((psa_key_type_t)0x4004) + + .. summary:: + ML-KEM public (encapsulation) key. + + .. versionadded:: 1.3 + + The bit size used in the attributes of an ML-KEM public key is the same as the corresponding private key. See `PSA_KEY_TYPE_ML_KEM_KEY_PAIR`. + + .. subsection:: Compatible algorithms + + .. hlist:: + + * `PSA_ALG_ML_KEM` (encapsulation only) + + .. subsection:: Key format + + An ML-KEM public key is the :math:`ek` output of ``ML-KEM.KeyGen()``, defined in `[FIPS203]` §7.1. + + In calls to :code:`psa_import_key()`, :code:`psa_export_key()`, and :code:`psa_export_public_key()`, the public-key data format is :math:`ek`. + + .. rationale:: + + This format is the same as that specified for X.509 in :cite-title:`LAMPS-MLKEM`. + + The size of the public key depends on the ML-KEM parameter set as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Public-key size in bytes + ML-KEM-512, 800 + ML-KEM-768, 1184 + ML-KEM-1024, 1568 + +.. macro:: PSA_KEY_TYPE_IS_ML_KEM + :definition: /* specification-defined value */ + + .. summary:: + Whether a key type is an ML-DSA key, either a key pair or a public key. + + .. versionadded:: 1.3 + + .. param:: type + A key type: a value of type :code:`psa_key_type_t`. .. _spake2p-keys: diff --git a/doc/crypto/api/ops/algorithms.rst b/doc/crypto/api/ops/algorithms.rst index 764e50fd..007a70ee 100644 --- a/doc/crypto/api/ops/algorithms.rst +++ b/doc/crypto/api/ops/algorithms.rst @@ -286,20 +286,24 @@ Support macros The following composite algorithms require a hash algorithm: - * `PSA_ALG_DETERMINISTIC_ECDSA()` - * `PSA_ALG_ECDSA()` - * `PSA_ALG_HKDF()` - * `PSA_ALG_HKDF_EXPAND()` - * `PSA_ALG_HKDF_EXTRACT()` - * `PSA_ALG_HMAC()` - * `PSA_ALG_JPAKE()` - * `PSA_ALG_PBKDF2_HMAC()` - * `PSA_ALG_RSA_OAEP()` - * `PSA_ALG_RSA_PKCS1V15_SIGN()` - * `PSA_ALG_RSA_PSS()` - * `PSA_ALG_RSA_PSS_ANY_SALT()` - * `PSA_ALG_SP800_108_COUNTER_HMAC()` - * `PSA_ALG_SPAKE2P_CMAC()` - * `PSA_ALG_SPAKE2P_HMAC()` - * `PSA_ALG_TLS12_PRF()` - * `PSA_ALG_TLS12_PSK_TO_MS()` + * `PSA_ALG_DETERMINISTIC_ECDSA` + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + * `PSA_ALG_ECDSA` + * `PSA_ALG_HASH_ML_DSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_HKDF` + * `PSA_ALG_HKDF_EXPAND` + * `PSA_ALG_HKDF_EXTRACT` + * `PSA_ALG_HMAC` + * `PSA_ALG_JPAKE` + * `PSA_ALG_PBKDF2_HMAC` + * `PSA_ALG_RSA_OAEP` + * `PSA_ALG_RSA_PKCS1V15_SIGN` + * `PSA_ALG_RSA_PSS` + * `PSA_ALG_RSA_PSS_ANY_SALT` + * `PSA_ALG_SP800_108_COUNTER_HMAC` + * `PSA_ALG_SPAKE2P_CMAC` + * `PSA_ALG_SPAKE2P_HMAC` + * `PSA_ALG_TLS12_PRF` + * `PSA_ALG_TLS12_PSK_TO_MS` diff --git a/doc/crypto/api/ops/hash.rst b/doc/crypto/api/ops/hash.rst index d48bd1eb..32948603 100644 --- a/doc/crypto/api/ops/hash.rst +++ b/doc/crypto/api/ops/hash.rst @@ -156,6 +156,17 @@ Hash algorithms SHA-512/256 is defined in :cite:`FIPS180-4`. +.. macro:: PSA_ALG_SHA_256_192 + :definition: ((psa_algorithm_t)0x0200000E) + + .. summary:: + The SHA-256/192 message digest algorithm. + + .. versionadded:: 1.3 + + SHA-256/192 is the first 192 bits (24 bytes) of the SHA-256 output. + SHA-256 is defined in :cite:`FIPS180-4`. + .. macro:: PSA_ALG_SHA3_224 :definition: ((psa_algorithm_t)0x02000010) @@ -192,14 +203,15 @@ Hash algorithms :definition: ((psa_algorithm_t)0x02000015) .. summary:: - The first 512 bits (64 bytes) of the output from SHAKE256. + The SHAKE256/512 message digest algorithm. .. versionadded:: 1.1 - This is used for pre-hashing in Ed448ph, see `PSA_ALG_ED448PH`. - + SHAKE256/512 is the first 512 bits (64 bytes) of the SHAKE256 output. The SHAKE256 XOF is defined in :cite:`FIPS202`. + This is the pre-hashing for Ed448ph, see `PSA_ALG_ED448PH`, and can be used as pre-hashing for ML-DSA or SLH-DSA, see `PSA_ALG_HASH_ML_DSA` and `PSA_ALG_HASH_SLH_DSA`. + .. note:: To use SHAKE256 as an XOF, see :secref:`xof` and `PSA_ALG_SHAKE256`. @@ -216,6 +228,48 @@ Hash algorithms It is recommended that these compound algorithms are not supported with `PSA_ALG_SHAKE256_512`. +.. macro:: PSA_ALG_SHAKE128_256 + :definition: ((psa_algorithm_t)0x02000016) + + .. summary:: + The SHAKE128/256 message digest algorithm. + + .. versionadded:: 1.3 + + SHAKE128/256 is the first 256 bits (32 bytes) of the SHAKE128 output. + The SHAKE128 XOF is defined in :cite:`FIPS202`. + + This can be used as pre-hashing for ML-DSA or SLH-DSA, see `PSA_ALG_HASH_ML_DSA` and `PSA_ALG_HASH_SLH_DSA`. + + .. note:: + To use SHAKE128 as an XOF, see :secref:`xof` and `PSA_ALG_SHAKE128`. + + .. 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_192 + :definition: ((psa_algorithm_t)0x02000017) + + .. summary:: + The SHAKE256/192 message digest algorithm. + + .. versionadded:: 1.3 + + SHAKE256/192 is the first 192 bits (24 bytes) of the SHAKE256 output. + SHAKE256 is defined in :cite:`FIPS202`. + +.. macro:: PSA_ALG_SHAKE256_256 + :definition: ((psa_algorithm_t)0x02000018) + + .. summary:: + The SHAKE256/256 message digest algorithm. + + .. versionadded:: 1.3 + + SHAKE256/256 is the first 256 bits (32 bytes) of the SHAKE256 output. + SHAKE256 is defined in :cite:`FIPS202`. + .. macro:: PSA_ALG_SM3 :definition: ((psa_algorithm_t)0x02000014) diff --git a/doc/crypto/api/ops/key-encapsulation.rst b/doc/crypto/api/ops/key-encapsulation.rst index 4a63dd03..8e146fc6 100644 --- a/doc/crypto/api/ops/key-encapsulation.rst +++ b/doc/crypto/api/ops/key-encapsulation.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2024-2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2024-2026 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -108,6 +108,49 @@ The key derivation, encryption, and authentication steps are left to the applica * `PSA_ECC_FAMILY_BRAINPOOL_P_R1` * `PSA_ECC_FAMILY_MONTGOMERY` +.. _ml-kem-algorithms: + +Module Lattice-based key-encapsulation algorithm +------------------------------------------------ + +ML-KEM is defined in :cite-title:`FIPS203`. +ML-KEM has three parameter sets which provide differing security strengths. + +The generation of an ML-KEM key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`ml-kem-keys`. + +See `[FIPS203]` §8 for details on the parameter sets. + +.. macro:: PSA_ALG_ML_KEM + :definition: ((psa_algorithm_t)0x0c000200) + + .. summary:: + Module Lattice-based key-encapsulation mechanism (ML-KEM). + + .. versionadded:: 1.3 + + This is the ML-KEM key-encapsulation algorithm, defined by `[FIPS203]`. + ML-KEM requires an ML-KEM key, which determines the ML-KEM parameter set for the operation. + + When using ML-KEM, the size of the encapsulation data returned by a call to :code:`psa_encapsulate()` is as follows: + + .. csv-table:: + :align: left + :header-rows: 1 + + Parameter set, Encapsulation data size in bytes + ML-KEM-512, 768 + ML-KEM-768, 1088 + ML-KEM-1024, 1568 + + The 32-byte shared output key that is produced by ML-KEM is pseudorandom. + Although it can be used directly as an encryption key, it is recommended to use the output key as an input to a key-derivation operation to produce additional cryptographic keys. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_KEM_KEY_PAIR` + | `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY` (encapsulation only) + Key-encapsulation functions --------------------------- diff --git a/doc/crypto/api/ops/signature.rst b/doc/crypto/api/ops/signature.rst index 43294969..3b851d5d 100644 --- a/doc/crypto/api/ops/signature.rst +++ b/doc/crypto/api/ops/signature.rst @@ -25,6 +25,10 @@ The |API| supports the following signature schemes: * :secref:`rsa-sign-algorithms` * :secref:`ecdsa-sign-algorithms` * :secref:`eddsa-sign-algorithms` +* :secref:`slh-dsa-algorithms` +* :secref:`ml-dsa-algorithms` +* :secref:`lms-algorithms` +* :secref:`xmss-algorithms` .. rubric:: Types of signature algorithm @@ -46,6 +50,10 @@ There are three categories of asymmetric signature algorithm in the |API|: | `PSA_ALG_DETERMINISTIC_ECDSA` | `PSA_ALG_ED25519PH` | `PSA_ALG_ED448PH` + | `PSA_ALG_HASH_SLH_DSA` + | `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + | `PSA_ALG_HASH_ML_DSA` + | `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` * Message signature algorithms that do not separate the message processing from the signature calculations. This approach can provide better security against certain types of attack. @@ -57,6 +65,14 @@ There are three categories of asymmetric signature algorithm in the |API|: | `PSA_ALG_PURE_EDDSA` | `PSA_ALG_EDDSA_CTX` + | `PSA_ALG_SLH_DSA` + | `PSA_ALG_DETERMINISTIC_SLH_DSA` + | `PSA_ALG_ML_DSA` + | `PSA_ALG_DETERMINISTIC_ML_DSA` + | `PSA_ALG_LMS` + | `PSA_ALG_HSS` + | `PSA_ALG_XMSS` + | `PSA_ALG_XMSS_MT` * Specialized signature algorithms, that use part of a standard signature algorithm within a specific protocol. It is recommended that these algorithms are only used for that purpose, with inputs as specified by the higher-level protocol. See the individual algorithm descriptions for details on their usage. @@ -759,6 +775,822 @@ The development of EdDSA resulted in a total of five distinct 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`. +SLH-DSA has twelve parameter sets which provide differing security strengths, trade-off between signature size and computation cost, and selection between SHA2 and SHAKE-based hashing. + +SLH-DSA keys are fairly compact, 32, 48, or 64 bytes for the public key, and double that for the key pair. +SLH-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 7.8kB and 49kB depending on the selected parameter set. +An SLH-DSA signature has the structure described in `[FIPS205]` §9.2, Figure 17. + +See `[FIPS205]` §11 for details on the parameter sets, and the public key and generated signature sizes. + +The generation of an SLH-DSA key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`slh-dsa-keys`. + +`[FIPS205]` defines pure and pre-hashed variants of the signature scheme, which can either be hedged (randomized) or deterministic. +Four algorithms are defined to support these variants: `PSA_ALG_SLH_DSA`, `PSA_ALG_DETERMINISTIC_SLH_DSA`, `PSA_ALG_HASH_SLH_DSA()`, and `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()`. + +.. _slh-dsa-deterministic-signatures: + +.. rubric:: Hedged and deterministic signatures + +Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. +Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs. + +Signature verification does not distinguish between a hedged and a deterministic signature. +Either hedged or deterministic algorithms can be used when verifying a signature. + +When computing a signature, the key's permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. +When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key's permitted-algorithm policy. + +.. note:: + + The hedged version provides message secrecy and some protection against side-channels. + `[FIPS205]` recommends that users should use the hedged version if either of these issues are a concern. + The deterministic variant should only be used if the implementation does not include any source of randomness. + +.. admonition:: Implementation note + + `[FIPS205]` recommends that implementations use an approved random number generator to provide the random value in the hedged version. + However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant. + +.. rationale:: + + The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in `[FIPS205]`. + + However, the |API| gives distinct algorithm identifiers for the hedged and deterministic variants for the following reasons: + + * `[FIPS205]` §9.1 recommends that SLH-DSA signing keys are only used to compute either deterministic, or hedged, signatures, but not both. + Supporting this recommendation requires separate algorithm identifiers, and requiring an exact policy match for signature computation. + * Enable an application use case to require a specific variant. + +.. rubric:: Pure and pre-hashed algorithms + +The pre-hashed signature computation *HashSLH-DSA* generates distinct signatures to a pure signature *SLH-DSA*, with the same key and message hashing algorithm. + +An SLH-DSA signature can only be verified with an SLH-DSA algorithm. +A HashSLH-DSA signature can only be verified with a HashSLH-DSA algorithm. + +:numref:`tab-slh-dsa-oid` lists the hash algorithm OIDs to use with the HashSLH-DSA algorithm. +Note that for HashSLH-DSA the DER-encoded OID includes the tag and length. + +.. csv-table:: Hash algorithm OID to use in HashSLH-DSA + :name: tab-slh-dsa-oid + :header-rows: 1 + :class: longtable + :widths: 6 7 7 8 + + Hash algorithm, OID (dot notation), OID (ASN.1 hex), Reference + :code:`PSA_ALG_SHA_256`, 2.16.840.1.101.3.4.2.1, ``0609608648016503040201``, :RFC-title:`8017#B.1` + :code:`PSA_ALG_SHA_512_256`, 2.16.840.1.101.3.4.2.6, ``0609608648016503040206``, :RFC:`8017#B.1` + :code:`PSA_ALG_SHA_384`, 2.16.840.1.101.3.4.2.2, ``0609608648016503040202``, :RFC:`8017#B.1` + :code:`PSA_ALG_SHA_512`, 2.16.840.1.101.3.4.2.3, ``0609608648016503040203``, :RFC:`8017#B.1` + :code:`PSA_ALG_SHA3_256`, 2.16.840.1.101.3.4.2.8, ``0609608648016503040208``, :RFC-title:`9688#2` + :code:`PSA_ALG_SHA3_384`, 2.16.840.1.101.3.4.2.9, ``0609608648016503040209``, :RFC:`9688#2` + :code:`PSA_ALG_SHA3_512`, 2.16.840.1.101.3.4.2.10, ``060960864801650304020a``, :RFC:`9688#2` + :code:`PSA_ALG_SHAKE128_256`, 2.16.840.1.101.3.4.2.11, ``060960864801650304020b``, :RFC-title:`8702#2` + :code:`PSA_ALG_SHAKE256_512`, 2.16.840.1.101.3.4.2.12, ``060960864801650304020c``, :RFC:`8702#2` + :code:`PSA_ALG_SM3`, 1.2.156.10197.1.504, ``06082a811ccf55018378``, :cite-title:`SM3-draft` §8.1.3 + +.. _slh-dsa-contexts: + +.. rubric:: Contexts + +All SLH-DSA algorithms can be used with contexts, which enables domain-separation when signatures are made of different message structures with the same key. +Context values are arbitrary strings between zero and 255 bytes in length. + +* The signature functions without a context parameter provide a zero-length context when computing or verifying SLH-DSA signatures. +* To provide a context, use the ``psa_xxxx_with_context()`` signature functions with a context parameter, such as :code:`psa_sign_message_with_context()`. + +.. macro:: PSA_ALG_SLH_DSA + :definition: ((psa_algorithm_t) 0x06004000) + + .. summary:: + Stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA). + + .. versionadded:: 1.3 + + This algorithm can only be used with the message signature functions. + For example, :code:`psa_sign_message()` or :code:`psa_verify_message_with_context()`. + + This is the pure SLH-DSA digital signature algorithm, defined by :cite-title:`FIPS205`, using hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + This algorithm has a context parameter. + See the `notes on SLH-DSA contexts `_. + + 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 :code:`psa_sign_message()` or :code:`psa_sign_message_with_context()`. + * `PSA_ALG_SLH_DSA` or `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to :code:`psa_verify_message()` or :code:`psa_verify_message_with_context()`. + + .. 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 :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_SLH_DSA + :definition: ((psa_algorithm_t) 0x06004100) + + .. summary:: + Deterministic stateless hash-based digital signature algorithm without pre-hashing (SLH-DSA). + + .. versionadded:: 1.3 + + This algorithm can only be used with the message signature functions. + For example, :code:`psa_sign_message()` or :code:`psa_verify_message_with_context()`. + + This is the pure SLH-DSA digital signature algorithm, defined by `[FIPS205]`, without hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_SLH_DSA` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + This algorithm has a context parameter. + See the `notes on SLH-DSA contexts `_. + + 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 :code:`psa_sign_message()` or :code:`psa_sign_message_with_context()`. + * `PSA_ALG_SLH_DSA` or `PSA_ALG_DETERMINISTIC_SLH_DSA` as the algorithm in a call to :code:`psa_verify_message()` or :code:`psa_verify_message_with_context()`. + + .. 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 :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA). + + .. versionadded:: 1.3 + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding HashSLH-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed SLH-DSA digital signature algorithm, defined by `[FIPS205]`, using hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS205]` §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set. + + :numref:`tab-slh-dsa-oid` lists the hash algorithm OID values to use when implementing HashSLH-DSA. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + This algorithm has a context parameter. + See the `notes on SLH-DSA contexts `_. + + 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 a message or hash signing function, such as :code:`psa_sign_message()` or :code:`psa_sign_hash_with_context()`. + * `PSA_ALG_HASH_SLH_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to a signature verification function, such as :code:`psa_verify_message()` or :code:`psa_verify_hash()_with_context()`. + + .. 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 :code:`psa_sign_message()` or :code:`psa_sign_message_with_context()` with the message. + + * Calculate the hash of the message with :code:`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 either with :code:`psa_sign_hash()` or, if the protocol requires the use of a non-zero-length context, with :code:`psa_sign_hash_with_context()`. + + Verifying a signature is similar, using :code:`psa_verify_message()` or :code:`psa_verify_hash()` instead of the signature function, or :code:`psa_verify_message_with_context()` or :code:`psa_verify_hash_with_context()` if a non-zero-=length context has been used. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Deterministic stateless hash-based digital signature algorithm with pre-hashing (HashSLH-DSA). + + .. versionadded:: 1.3 + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding deterministic HashSLH-DSA signature algorithm, using ``hash_alg`` to pre-hash the message. + + Unspecified if ``hash_alg`` is not a supported hash algorithm. + + This algorithm can be used with both the message and hash signature functions. + + This is the pre-hashed SLH-DSA digital signature algorithm, defined by `[FIPS205]`, without hedging. + SLH-DSA requires an SLH-DSA key, which determines the SLH-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS205]` §10.2 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen SLH-DSA parameter set. + + :numref:`tab-slh-dsa-oid` lists the hash algorithm OID values to use when implementing HashSLH-DSA. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_HASH_SLH_DSA()` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + This algorithm has a context parameter. + See the `notes on SLH-DSA contexts `_. + + 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 :code:`psa_sign_message()` and :code:`psa_sign_hash()`. + * `PSA_ALG_HASH_SLH_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA()` as the algorithm in a call to :code:`psa_verify_message()` and :code:`psa_verify_hash()`. + + .. note:: + The signature produced by HashSLH-DSA is distinct from that produced by SLH-DSA. + + .. subsection:: Usage + + See `PSA_ALG_HASH_SLH_DSA()` for example usage. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR()` + | :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY()` (signature verification only) + +.. macro:: PSA_ALG_IS_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is SLH-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is an SLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is HashSLH-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + +.. macro:: PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic HashSLH-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_HEDGED_HASH_SLH_DSA()`. + +.. macro:: PSA_ALG_IS_HEDGED_HASH_SLH_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is hedged HashSLH-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a hedged HashSLH-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_SLH_DSA()` and `PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA()`. + +.. _ml-dsa-algorithms: + +Module Lattice-based signature algorithms +----------------------------------------- + +The ML-DSA signature and verification scheme is defined in :cite-title:`FIPS204`. +ML-DSA has three parameter sets which provide differing security strengths. + +ML-DSA keys are large: 1.2--2.5kB for the public key, and triple that for the key pair. +ML-DSA signatures are much larger than those for RSA and Elliptic curve schemes, between 2.4kB and 4.6kB, depending on the selected parameter set. + +See `[FIPS204]` §4 for details on the parameter sets, and the key and generated signature sizes. + +The generation of an ML-DSA key depends on the full parameter specification. +The encoding of each parameter set into the key attributes is described in :secref:`ml-dsa-keys`. + +`[FIPS204]` 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_ML_DSA`, `PSA_ALG_DETERMINISTIC_ML_DSA`, `PSA_ALG_HASH_ML_DSA()`, and `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`. + +.. _ml-dsa-deterministic-signatures: + +.. rubric:: Hedged and deterministic signatures + +Hedging incorporates fresh randomness in the signature computation, resulting in distinct signatures on every signing operation when given identical inputs. +Deterministic signatures do not require additional random data, and result in an identical signature for the same inputs. + +Signature verification does not distinguish between a hedged and a deterministic signature. +Either hedged or deterministic algorithms can be used when verifying a signature. + +When computing a signature, the key's permitted-algorithm policy must match the requested algorithm, treating hedged and deterministic versions as distinct. +When verifying a signature, the hedged and deterministic versions of each algorithm are considered equivalent when checking the key's permitted-algorithm policy. + +.. note:: + + The hedged version provides message secrecy and some protection against side-channels. + `[FIPS204]` recommends that users should use the hedged version if either of these issues are a concern. + The deterministic variant should only be used if the implementation does not include any source of randomness. + +.. admonition:: Implementation note + + `[FIPS204]` recommends that implementations use an approved random number generator to provide the random value in the hedged version. + However, it notes that use of the hedged variant with a weak RNG is generally preferable to the deterministic variant. + +.. rationale:: + + The use of fresh randomness, or not, when computing a signature seems like an implementation decision based on the capability of the system, and its vulnerability to specific threats, following the recommendations in `[FIPS204]`. + + However, the |API| gives distinct algorithm identifiers for the hedged and deterministic variants, to enable an application use case to require a specific variant. + +.. rubric:: Pure and pre-hashed algorithms + +The pre-hashed signature computation *HashML-DSA* generates distinct signatures to a pure signature *ML-DSA*, with the same key and message hashing algorithm. + +An ML-DSA signature can only be verified with an ML-DSA algorithm. +A HashML-DSA signature can only be verified with a HashML-DSA algorithm. + +:numref:`tab-ml-dsa-oid` lists the hash algorithm OIDs to use with the HashML-DSA algorithm. +Note that for HashML-DSA the DER-encoded OID includes the tag and length. + +.. csv-table:: Hash algorithm OID to use in HashML-DSA + :name: tab-ml-dsa-oid + :header-rows: 1 + :class: longtable + :widths: 6 7 7 8 + + Hash algorithm, OID (dot notation), OID (ASN.1 hex), Reference + :code:`PSA_ALG_SHA_256`, 2.16.840.1.101.3.4.2.1, ``0609608648016503040201``, :RFC-title:`8017#B.1` + :code:`PSA_ALG_SHA_512_256`, 2.16.840.1.101.3.4.2.6, ``0609608648016503040206``, :RFC:`8017#B.1` + :code:`PSA_ALG_SHA_384`, 2.16.840.1.101.3.4.2.2, ``0609608648016503040202``, :RFC:`8017#B.1` + :code:`PSA_ALG_SHA_512`, 2.16.840.1.101.3.4.2.3, ``0609608648016503040203``, :RFC:`8017#B.1` + :code:`PSA_ALG_SHA3_256`, 2.16.840.1.101.3.4.2.8, ``0609608648016503040208``, :RFC-title:`9688#2` + :code:`PSA_ALG_SHA3_384`, 2.16.840.1.101.3.4.2.9, ``0609608648016503040209``, :RFC:`9688#2` + :code:`PSA_ALG_SHA3_512`, 2.16.840.1.101.3.4.2.10, ``060960864801650304020a``, :RFC:`9688#2` + :code:`PSA_ALG_SHAKE128_256`, 2.16.840.1.101.3.4.2.11, ``060960864801650304020b``, :RFC-title:`8702#2` + :code:`PSA_ALG_SHAKE256_512`, 2.16.840.1.101.3.4.2.12, ``060960864801650304020c``, :RFC:`8702#2` + :code:`PSA_ALG_SM3`, 1.2.156.10197.1.504, ``06082a811ccf55018378``, :cite-title:`SM3-draft` §8.1.3 + +.. _ml-dsa-contexts: + +.. rubric:: Contexts + +All ML-DSA algorithms can be used with contexts, which enables domain-separation when signatures are made of different message structures with the same key. +Context values are arbitrary strings between zero and 255 bytes in length. + +* The signature functions without a context parameter provide a zero-length context when computing or verifying ML-DSA signatures. +* To provide a context, use the ``psa_xxxx_with_context()`` signature functions with a context parameter, such as :code:`psa_sign_message_with_context()`. + +.. macro:: PSA_ALG_ML_DSA + :definition: ((psa_algorithm_t) 0x06004400) + + .. summary:: + Module lattice-based digital signature algorithm without pre-hashing (ML-DSA). + + .. versionadded:: 1.3 + + This algorithm can only be used with the message signature and verify functions. + For example, :code:`psa_sign_message()` or :code:`psa_verify_message_with_context()`. + + This is the pure ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, using hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + This algorithm has a context parameter. + See the `notes on ML-DSA contexts `_. + + When `PSA_ALG_ML_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_ML_DSA` as the algorithm in a call to :code:`psa_sign_message()` or :code:`psa_sign_message_with_context()`. + * `PSA_ALG_ML_DSA` or `PSA_ALG_DETERMINISTIC_ML_DSA` as the algorithm in a call to :code:`psa_verify_message()` or :code:`psa_verify_message_with_context()`. + + .. note:: + To sign or verify the pre-computed hash of a message using ML-DSA, the HashML-DSA algorithms (`PSA_ALG_HASH_ML_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`) can also be used with :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_ML_DSA + :definition: ((psa_algorithm_t) 0x06004500) + + .. summary:: + Deterministic module lattice-based digital signature algorithm without pre-hashing (ML-DSA). + + .. versionadded:: 1.3 + + This algorithm can only be used with the message signature and verify functions. + For example, :code:`psa_sign_message()` or :code:`psa_verify_message_with_context()`. + + This is the pure ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, without hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + This algorithm is deterministic: each invocation with the same inputs returns an identical signature. + + .. warning:: + It is recommended to use the hedged `PSA_ALG_ML_DSA` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + This algorithm has a context parameter. + See the `notes on ML-DSA contexts `_. + + When `PSA_ALG_DETERMINISTIC_ML_DSA` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_ML_DSA` as the algorithm in a call to :code:`psa_sign_message()` or :code:`psa_sign_message_with_context()`. + * `PSA_ALG_ML_DSA` or `PSA_ALG_DETERMINISTIC_ML_DSA` as the algorithm in a call to :code:`psa_verify_message()` or :code:`psa_verify_message_with_context()`. + + .. note:: + To sign or verify the pre-computed hash of a message using ML-DSA, the HashML-DSA algorithms (`PSA_ALG_HASH_ML_DSA()` and `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()`) can also be used with :code:`psa_sign_hash()` and :code:`psa_verify_hash()`. + + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | :code:`PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Module lattice-based digital signature algorithm with pre-hashing (HashML-DSA). + + .. versionadded:: 1.3 + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding HashML-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 ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, using hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS204]` §5.4 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen ML-DSA parameter set. + + :numref:`tab-ml-dsa-oid` lists the hash algorithm OID values to use when implementing HashML-DSA. + + This algorithm is randomized: each invocation returns a different, equally valid signature. + See the `notes on hedged signatures `_. + + This algorithm has a context parameter. + See the `notes on ML-DSA contexts `_. + + When `PSA_ALG_HASH_ML_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_HASH_ML_DSA()` as the algorithm in a call to a message or hash signing function, such as :code:`psa_sign_message()` or :code:`psa_sign_hash_with_context()`. + * `PSA_ALG_HASH_ML_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` as the algorithm in a call to a signature verification function, such as :code:`psa_verify_message()` or :code:`psa_verify_hash()_with_context()`. + + .. note:: + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Usage + + This is a hash-and-sign algorithm. To calculate a signature, use one of the following approaches: + + * Call :code:`psa_sign_message()` or :code:`psa_sign_message_with_context()` with the message. + + * Calculate the hash of the message with :code:`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 either with :code:`psa_sign_hash()` or, if the protocol requires the use of a non-zero-length context, with :code:`psa_sign_hash_with_context()`. + + Verifying a signature is similar, using :code:`psa_verify_message()` or :code:`psa_verify_hash()` instead of the signature function, or :code:`psa_verify_message_with_context()` or :code:`psa_verify_hash_with_context()` if a non-zero-=length context has been used. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_DETERMINISTIC_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Deterministic module lattice-based digital signature algorithm with pre-hashing (HashML-DSA). + + .. versionadded:: 1.3 + + .. param:: hash_alg + A hash algorithm: a value of type :code:`psa_algorithm_t` such that :code:`PSA_ALG_IS_HASH(hash_alg)` is true. + This includes :code:`PSA_ALG_ANY_HASH` when specifying the algorithm in a key policy. + + .. return:: + The corresponding deterministic HashML-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 ML-DSA digital signature algorithm, defined by :cite-title:`FIPS204`, without hedging. + ML-DSA requires an ML-DSA key, which determines the ML-DSA parameter set for the operation. + + .. note:: + For the pre-hashing, `[FIPS204]` §5.4 recommends the use of an approved hash function with an equivalent, or better, security strength than the chosen ML-DSA parameter set. + + :numref:`tab-ml-dsa-oid` lists the hash algorithm OID values to use when implementing HashML-DSA. + + 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_ML_DSA()` algorithm instead, when supported by the implementation. + See the `notes on deterministic signatures `_. + + This algorithm has a context parameter. + See the `notes on ML-DSA contexts `_. + + When `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` is used as a permitted algorithm in a key policy, this permits: + + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` as the algorithm in a call to a message or hash signing function, such as :code:`psa_sign_message()` or :code:`psa_sign_hash_with_context()`. + * `PSA_ALG_HASH_ML_DSA()` or `PSA_ALG_DETERMINISTIC_HASH_ML_DSA()` as the algorithm in a call to a signature verification function, such as :code:`psa_verify_message()` or :code:`psa_verify_hash()_with_context()`. + + .. note:: + The signature produced by HashML-DSA is distinct from that produced by ML-DSA. + + .. subsection:: Usage + + See `PSA_ALG_HASH_ML_DSA()` for example usage. + + .. subsection:: Compatible key types + + | `PSA_KEY_TYPE_ML_DSA_KEY_PAIR` + | `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_IS_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is ML-DSA, without pre-hashing. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a pure ML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + .. note:: + Use `PSA_ALG_IS_HASH_ML_DSA()` to determine if an algorithm identifier is a HashML-DSA algorithm. + +.. macro:: PSA_ALG_IS_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is HashML-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a HashML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + .. note:: + Use `PSA_ALG_IS_ML_DSA()` to determine if an algorithm identifier is a pre-hashed ML-DSA algorithm. + +.. macro:: PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is deterministic HashML-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a deterministic HashML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_ML_DSA()` and `PSA_ALG_IS_HEDGED_HASH_ML_DSA()`. + +.. macro:: PSA_ALG_IS_HEDGED_HASH_ML_DSA + :definition: /* specification-defined value */ + + .. summary:: + Whether the specified algorithm is hedged HashML-DSA. + + .. versionadded:: 1.3 + + .. param:: alg + An algorithm identifier: a value of type :code:`psa_algorithm_t`. + + .. return:: + ``1`` if ``alg`` is a hedged HashML-DSA algorithm, ``0`` otherwise. + + This macro can return either ``0`` or ``1`` if ``alg`` is not a supported algorithm identifier. + + See also `PSA_ALG_IS_HASH_ML_DSA()` and `PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA()`. + +.. _lms-algorithms: + +Leighton-Micali Signature algorithms +------------------------------------ + +The Leighton-Micali Signatures (LMS) and multi-level Hierarchical Signature Scheme (HSS) schemes are defined in :rfc-title:`8554`. + +For the |API| to support signature verification, it is only necessary to define a public keys for these schemes, and the default public key formats for import and export. + +.. rationale:: + + At present, it is not expected that the |API| will be used to generate LMS or HSS private keys, or to carry out signing operations. + However, there is value in supporting verification of LMS and HSS signatures. + Therefore, the |API| does not support LMS or HSS key pairs, or the associated signing operations. + +.. note:: + A full set of NIST-approved parameter sets for LMS and HSS is defined in :cite-title:`SP800-208` §4, with the additional IANA identifiers defined in :rfc-title:`9858`. + +.. macro:: PSA_ALG_LMS + :definition: ((psa_algorithm_t) 0x06004800) + + .. summary:: + Leighton-Micali Signatures (LMS) signature algorithm. + + .. versionadded:: 1.3 + + This message-signature algorithm can only be used with the :code:`psa_verify_message()` function. + LMS does not have a context parameter. + However, :code:`psa_verify_message_with_context()` can be used with a zero-length context. + + This is the LMS stateful hash-based signature algorithm, defined by :rfc-title:`8554`. + LMS requires an LMS key. + The key and the signature must both encode the same LMS parameter set, which is used for the verification procedure. + + .. note:: + LMS signature calculation is not supported. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_LMS_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_HSS + :definition: ((psa_algorithm_t) 0x06004900) + + .. summary:: + Hierarchical Signature Scheme (HSS) signature algorithm. + + .. versionadded:: 1.3 + + This message-signature algorithm can only be used with the :code:`psa_verify_message()` function. + HSS does not have a context parameter. + However, :code:`psa_verify_message_with_context()` can be used with a zero-length context. + + This is the HSS stateful hash-based signature algorithm, defined by :rfc-title:`8554`. + HSS requires an HSS key. + The key and the signature must both encode the same HSS parameter set, which is used for the verification procedure. + + .. note:: + HSS signature calculation is not supported. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_HSS_PUBLIC_KEY` (signature verification only) + +.. _xmss-algorithms: + +XMSS and |XMSS^MT| algorithms +----------------------------- + +The eXtended Merkle Signature Scheme (XMSS), and the multi-tree variant |XMSS^MT|, are defined in :rfc-title:`8391`. + +For the |API| to support signature verification, it is only necessary to define public keys for these schemes, and the default public key formats for import and export. + +.. rationale:: + + At present, it is not expected that the |API| will be used to generate XMSS or |XMSS^MT| private keys, or to carry out signing operations. + However, there is value in supporting verification of XMSS and |XMSS^MT| signatures. + Therefore, the |API| does not support XMSS or |XMSS^MT| key pairs, or the associated signing operations. + +.. note:: + A full set of NIST-approved parameter sets for XMSS or |XMSS^MT| is defined in :cite-title:`SP800-208` §5. + +.. macro:: PSA_ALG_XMSS + :definition: ((psa_algorithm_t) 0x06004A00) + + .. summary:: + eXtended Merkle Signature Scheme (XMSS) signature algorithm. + + .. versionadded:: 1.3 + + This message-signature algorithm can only be used with the :code:`psa_verify_message()` function. + XMSS does not have a context parameter. + However, :code:`psa_verify_message_with_context()` can be used with a zero-length context. + + This is the XMSS stateful hash-based signature algorithm, defined by :rfc-title:`8391`. + XMSS requires an XMSS key. + The key and the signature must both encode the same XMSS parameter set, which is used for the verification procedure. + + .. note:: + XMSS signature calculation is not supported. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_XMSS_PUBLIC_KEY` (signature verification only) + +.. macro:: PSA_ALG_XMSS_MT + :definition: ((psa_algorithm_t) 0x06004B00) + + .. summary:: + Multi-tree eXtended Merkle Signature Scheme (|XMSS^MT|) signature algorithm. + + .. versionadded:: 1.3 + + This message-signature algorithm can only be used with the :code:`psa_verify_message()` function. + |XMSS^MT| does not have a context parameter. + However, :code:`psa_verify_message_with_context()` can be used with a zero-length context. + + This is the |XMSS^MT| stateful hash-based signature algorithm, defined by :rfc-title:`8391`. + |XMSS^MT| requires an |XMSS^MT| key. + The key and the signature must both encode the same |XMSS^MT| parameter set, which is used for the verification procedure. + + .. note:: + |XMSS^MT| signature calculation is not supported. + + .. subsection:: Compatible key types + + | :code:`PSA_KEY_TYPE_XMSS_MT_PUBLIC_KEY` (signature verification only) .. _single-part-signature: @@ -1400,6 +2232,10 @@ Support macros * `PSA_ALG_RSA_PSS_ANY_SALT` * `PSA_ALG_ECDSA` * `PSA_ALG_DETERMINISTIC_ECDSA` + * `PSA_ALG_HASH_SLH_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_SLH_DSA` + * `PSA_ALG_HASH_ML_DSA` + * `PSA_ALG_DETERMINISTIC_HASH_ML_DSA` The following sequence of operations shows how `PSA_ALG_ANY_HASH` can be used in a key policy: diff --git a/doc/crypto/api/ops/xof.rst b/doc/crypto/api/ops/xof.rst index 68b45635..873ac3d1 100644 --- a/doc/crypto/api/ops/xof.rst +++ b/doc/crypto/api/ops/xof.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2025-2026 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. header:: psa/crypto @@ -54,7 +54,7 @@ XOF algorithms Some fixed output-length hash algorithms based on SHAKE128 are also provided in the |API|: - * :code:`PSA_ALG_SHAKE128_256` --- defined in :cite-title:`PSA-PQC` + * `PSA_ALG_SHAKE128_256` .. macro:: PSA_ALG_SHAKE256 :definition: ((psa_algorithm_t)0x0D000200) @@ -70,9 +70,9 @@ XOF algorithms Some fixed output-length hash algorithms based on SHAKE256 are also provided in the |API|: - * :code:`PSA_ALG_SHAKE256_192` --- defined in `[PSA-PQC]` - * :code:`PSA_ALG_SHAKE256_256` --- defined in `[PSA-PQC]` - * :code:`PSA_ALG_SHAKE256_512` + * `PSA_ALG_SHAKE256_192` + * `PSA_ALG_SHAKE256_256` + * `PSA_ALG_SHAKE256_512` .. macro:: PSA_ALG_ASCON_XOF128 :definition: ((psa_algorithm_t)0x0D000300) diff --git a/doc/crypto/appendix/encodings.rst b/doc/crypto/appendix/encodings.rst index 1e19e7c3..4fa12dbd 100644 --- a/doc/crypto/appendix/encodings.rst +++ b/doc/crypto/appendix/encodings.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2022-2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2022-2026 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. _appendix-encodings: @@ -129,12 +129,16 @@ The defined values for HASH-TYPE are shown in :numref:`table-hash-type`. SHA-512, ``0x0B``, `PSA_ALG_SHA_512`, ``0x0200000B`` SHA-512/224, ``0x0C``, `PSA_ALG_SHA_512_224`, ``0x0200000C`` SHA-512/256, ``0x0D``, `PSA_ALG_SHA_512_256`, ``0x0200000D`` + SHA-256/192, ``0x0E``, `PSA_ALG_SHA_256_192`, ``0x0200000E`` SHA3-224, ``0x10``, `PSA_ALG_SHA3_224`, ``0x02000010`` SHA3-256, ``0x11``, `PSA_ALG_SHA3_256`, ``0x02000011`` SHA3-384, ``0x12``, `PSA_ALG_SHA3_384`, ``0x02000012`` SHA3-512, ``0x13``, `PSA_ALG_SHA3_512`, ``0x02000013`` SM3, ``0x14``, `PSA_ALG_SM3`, ``0x02000014`` SHAKE256-512, ``0x15``, `PSA_ALG_SHAKE256_512`, ``0x02000015`` + SHAKE128/256, ``0x16``, `PSA_ALG_SHAKE128_256`, ``0x02000016`` + SHAKE256/192, ``0x17``, `PSA_ALG_SHAKE256_192`, ``0x02000017`` + SHAKE256/256, ``0x18``, `PSA_ALG_SHAKE256_256`, ``0x02000018`` Ascon-Hash256, ``0x19``, `PSA_ALG_ASCON_HASH256`, ``0x02000019`` *wildcard* :sup:`a`, ``0xFF``, `PSA_ALG_ANY_HASH`, ``0x020000FF`` @@ -377,6 +381,18 @@ H = HASH-TYPE (see :numref:`table-hash-type`) for message signature algorithms t PureEdDSA without context, ``0x08``, `PSA_ALG_PURE_EDDSA`, ``0x06000800`` HashEdDSA, ``0x09``, `PSA_ALG_ED25519PH` and `PSA_ALG_ED448PH`, ``0x060009hh`` :sup:`c` PureEdDSA with context, ``0x0a``, `PSA_ALG_EDDSA_CTX`, ``0x06000a00`` + 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` + Hedged ML-DSA, ``0x44``, `PSA_ALG_ML_DSA`, ``0x06004400`` + Deterministic ML-DSA, ``0x45``, `PSA_ALG_DETERMINISTIC_ML_DSA`, ``0x06004500`` + Hedged HashML-DSA, ``0x46``, :code:`PSA_ALG_HASH_ML_DSA(hash)`, ``0x060046hh`` :sup:`a` + Deterministic HashML-DSA, ``0x47``, :code:`PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash)`, ``0x060047hh`` :sup:`a` + LMS, ``0x48``, :code:`PSA_ALG_LMS`, ``0x06004800`` + HSS, ``0x49``, :code:`PSA_ALG_HSS`, ``0x06004900`` + XMSS, ``0x4A``, :code:`PSA_ALG_XMSS`, ``0x06004A00`` + |XMSS^MT|, ``0x4B``, :code:`PSA_ALG_XMSS_MT`, ``0x06004B00`` a. ``hh`` is the HASH-TYPE for the hash algorithm, ``hash_alg``, used to construct the signature algorithm. @@ -468,6 +484,7 @@ The defined values for ENCAPS-TYPE are shown in :numref:`table-key-encapsulation Encapsulation algorithm, ENCAPS-TYPE, Algorithm identifier, Algorithm value ECIES (SEC1), ``0x01``, `PSA_ALG_ECIES_SEC1`, ``0x0C000100`` + ML-KEM, ``0x02``, `PSA_ALG_ML_KEM`, ``0x0C000200`` .. _pake-encoding: @@ -741,7 +758,8 @@ 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` - Diffie-Hellman, 4, See :secref:`dh-key-encoding` + SLH-DSA, 3, See :secref:`slh-dsa-key-encoding` + Finite field Diffie-Hellman, 4, See :secref:`dh-key-encoding` SPAKE2+, 8, See :secref:`spakep2-key-encoding` .. _simple-asymmetric-key-encoding: @@ -769,6 +787,14 @@ The defined values for NP-FAMILY and P are shown in :numref:`table-np-type`. Key family, Public/pair, PAIR, NP-FAMILY, P, Key type, Key value RSA, Public key, 0, 0, 1, `PSA_KEY_TYPE_RSA_PUBLIC_KEY`, ``0x4001`` , Key pair, 3, 0, 1, `PSA_KEY_TYPE_RSA_KEY_PAIR`, ``0x7001`` + ML-DSA, Public key, 0, 1, 0, `PSA_KEY_TYPE_ML_DSA_PUBLIC_KEY`, ``0x4002`` + , Key pair, 3, 1, 0, `PSA_KEY_TYPE_ML_DSA_KEY_PAIR`, ``0x7002`` + ML-KEM, Public key, 0, 2, 0, `PSA_KEY_TYPE_ML_KEM_PUBLIC_KEY`, ``0x4004`` + , Key pair, 3, 2, 0, `PSA_KEY_TYPE_ML_KEM_KEY_PAIR`, ``0x7004`` + LMS, Public key, 0, 3, 1, `PSA_KEY_TYPE_LMS_PUBLIC_KEY`, ``0x4007`` + HSS, Public key, 0, 4, 0, `PSA_KEY_TYPE_HSS_PUBLIC_KEY`, ``0x4008`` + XMSS, Public key, 0, 5, 1, `PSA_KEY_TYPE_XMSS_PUBLIC_KEY`, ``0x400B`` + |XMSS^MT|, Public key, 0, 6, 1, `PSA_KEY_TYPE_XMSS_MT_PUBLIC_KEY`, ``0x400D`` .. _ecc-key-encoding: @@ -806,6 +832,36 @@ The defined values for ECC-FAMILY and P are shown in :numref:`table-ecc-type`. a. The elliptic curve family values defined in the API also include the parity bit. The key type value is constructed from the elliptic curve family using either :code:`PSA_KEY_TYPE_ECC_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_ECC_KEY_PAIR(family)` as required. +.. _slh-dsa-key-encoding: + +SLH-DSA key encoding +^^^^^^^^^^^^^^^^^^^^ + +The key type for SLH-DSA keys defined in this specification are encoded as shown in :numref:`fig-slh-dsa-key-fields`. + +.. figure:: ../figure/encoding/slh_dsa_key.* + :name: fig-slh-dsa-key-fields + + SLH-DSA key encoding + +PAIR is either 0 for a public key, or 3 for a key pair. + +The defined values for FAMILY and P are shown in :numref:`table-slh-dsa-type`. + +.. csv-table:: SLH-DSA key family values + :name: table-slh-dsa-type + :header-rows: 1 + :align: left + :widths: auto + + SLH-DSA key family, FAMILY, P, SLH-DSA family :sup:`a`, Public-key value, Key-pair value + SLH-DSA-SHA2-\ *N*\ s, 0x01, 0, `PSA_SLH_DSA_FAMILY_SHA2_S`, ``0x4182``, ``0x7182`` + SLH-DSA-SHA2-\ *N*\ f, 0x02, 0, `PSA_SLH_DSA_FAMILY_SHA2_F`, ``0x4184``, ``0x7184`` + SLH-DSA-SHAKE-\ *N*\ s, 0x05, 1, `PSA_SLH_DSA_FAMILY_SHAKE_S`, ``0x418B``, ``0x718B`` + SLH-DSA-SHAKE-\ *N*\ f, 0x06, 1, `PSA_SLH_DSA_FAMILY_SHAKE_F`, ``0x418D``, ``0x718D`` + +a. The SLH-DSA family values defined in the API also include the parity bit. The key type value is constructed from the SLH-DSA family using either :code:`PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(family)` or :code:`PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(family)` as required. + .. _dh-key-encoding: Finite field Diffie Hellman key encoding diff --git a/doc/crypto/appendix/history.rst b/doc/crypto/appendix/history.rst index 1a79ea5c..8183e3a0 100644 --- a/doc/crypto/appendix/history.rst +++ b/doc/crypto/appendix/history.rst @@ -17,7 +17,6 @@ Changes between *1.4.1* and *1.5.0* Changes to the API ~~~~~~~~~~~~~~~~~~ - Relaxations ~~~~~~~~~~~ @@ -29,6 +28,16 @@ Clarifications and fixes Other changes ~~~~~~~~~~~~~ +* Integrated the PQC algorithms and key types from :cite-title:`PSA-PQC`. + + This provides support for LMS, HSS, XMSS, |XMSS^MT|, ML-DSA, SLH-DSA, and ML-KEM. + + - For LMS and HSS, see :secref:`lms-keys` and :secref:`lms-algorithms`. + - For XMSS and |XMSS^MT|, see :secref:`xmss-keys` and :secref:`xmss-algorithms`. + - For ML-DSA, see :secref:`ml-dsa-keys` and :secref:`ml-dsa-algorithms`. + - For SLH-DSA, see :secref:`slh-dsa-keys` and :secref:`slh-dsa-algorithms`. + - For ML-KEM, see :secref:`ml-kem-keys` and :secref:`ml-kem-algorithms`. + - Additional hash algorithms: `PSA_ALG_SHAKE128_256`, `PSA_ALG_SHAKE256_192`, `PSA_ALG_SHAKE256_256`, and `PSA_ALG_SHA_256_192`. Changes between *1.4.0* and *1.4.1* ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/crypto/appendix/specdef_values.rst b/doc/crypto/appendix/specdef_values.rst index d381870a..bbcfcd1f 100644 --- a/doc/crypto/appendix/specdef_values.rst +++ b/doc/crypto/appendix/specdef_values.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2020-2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2020-2026 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license .. _appendix-specdef-values: @@ -39,6 +39,12 @@ Algorithm macros #define PSA_ALG_DETERMINISTIC_ECDSA(hash_alg) \ ((psa_algorithm_t) (0x06000700 | ((hash_alg) & 0x000000ff))) + #define PSA_ALG_DETERMINISTIC_HASH_ML_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004700 | ((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 +54,12 @@ Algorithm macros #define PSA_ALG_GET_HASH(alg) \ (((alg) & 0x000000ff) == 0 ? PSA_ALG_NONE : 0x02000000 | ((alg) & 0x000000ff)) + #define PSA_ALG_HASH_ML_DSA(hash_alg) \ + ((psa_algorithm_t) (0x06004600 | ((hash_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))) @@ -75,6 +87,12 @@ Algorithm macros #define PSA_ALG_IS_CIPHER(alg) \ (((alg) & 0x7f000000) == 0x04000000) + #define PSA_ALG_IS_DETERMINISTIC_HASH_ML_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004700) + + #define PSA_ALG_IS_DETERMINISTIC_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004300) + #define PSA_ALG_IS_DETERMINISTIC_ECDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000700) @@ -92,11 +110,24 @@ 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_ML_DSA(alg) || PSA_ALG_IS_HASH_SLH_DSA(alg)) #define PSA_ALG_IS_HASH_EDDSA(alg) \ (((alg) & ~0x000000ff) == 0x06000900) + #define PSA_ALG_IS_HASH_ML_DSA(alg) \ + (((alg) & ~0x000001ff) == 0x06004600) + + #define PSA_ALG_IS_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000001ff) == 0x06004200) + + #define PSA_ALG_IS_HEDGED_HASH_ML_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004600) + + #define PSA_ALG_IS_HEDGED_HASH_SLH_DSA(alg) \ + (((alg) & ~0x000000ff) == 0x06004200) + #define PSA_ALG_IS_HKDF(alg) \ (((alg) & ~0x000000ff) == 0x08000100) @@ -130,6 +161,9 @@ Algorithm macros #define PSA_ALG_IS_MAC(alg) \ (((alg) & 0x7f000000) == 0x03000000) + #define PSA_ALG_IS_ML_DSA(alg) \ + (((alg) & ~0x00000100) == 0x06004400) + #define PSA_ALG_IS_PAKE(alg) \ (((alg) & 0x7f000000) == 0x0a000000) @@ -158,13 +192,17 @@ Algorithm macros (((alg) & 0x7f000000) == 0x06000000) #define PSA_ALG_IS_SIGN_HASH(alg) \ - (PSA_ALG_IS_SIGN(alg) && \ - (alg) != PSA_ALG_PURE_EDDSA && (alg) != PSA_ALG_EDDSA_CTX) + (PSA_ALG_IS_HASH_AND_SIGN(alg) || + (alg) == PSA_ALG_RSA_PKCS1V15_SIGN_RAW || + (alg) == PSA_ALG_ECDSA_ANY) #define PSA_ALG_IS_SIGN_MESSAGE(alg) \ (PSA_ALG_IS_SIGN(alg) && \ (alg) != PSA_ALG_ECDSA_ANY && (alg) != PSA_ALG_RSA_PKCS1V15_SIGN_RAW) + #define PSA_ALG_IS_SLH_DSA(alg) \ + (((alg) & ~0x00000100) == 0x06004000) + #define PSA_ALG_IS_SP800_108_COUNTER_HMAC(alg) \ (((alg) & ~0x000000ff) == 0x08000700) @@ -333,12 +371,27 @@ Key type macros #define PSA_KEY_TYPE_IS_KEY_PAIR(type) \ (((type) & 0x7000) == 0x7000) + #define PSA_KEY_TYPE_IS_ML_DSA(type) \ + (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4002) + + #define PSA_KEY_TYPE_IS_ML_KEM(type) \ + (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4004) + #define PSA_KEY_TYPE_IS_PUBLIC_KEY(type) \ (((type) & 0x7000) == 0x4000) #define PSA_KEY_TYPE_IS_RSA(type) \ (PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) == 0x4001) + #define PSA_KEY_TYPE_IS_SLH_DSA(type) \ + ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4180) + + #define PSA_KEY_TYPE_IS_SLH_DSA_KEY_PAIR(type) \ + (((type) & 0xff80) == 0x7180) + + #define PSA_KEY_TYPE_IS_SLH_DSA_PUBLIC_KEY(type) \ + (((type) & 0xff80) == 0x4180) + #define PSA_KEY_TYPE_IS_SPAKE2P(type) \ ((PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) & 0xff80) == 0x4400) @@ -363,6 +416,15 @@ Key type macros #define PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR(type) \ ((psa_key_type_t) ((type) & ~0x3000)) + #define PSA_KEY_TYPE_SLH_DSA_GET_FAMILY(type) \ + ((psa_slh_dsa_family_t) ((type) & 0x007f)) + + #define PSA_KEY_TYPE_SLH_DSA_KEY_PAIR(set) \ + ((psa_key_type_t) (0x7180 | ((set) & 0x007f))) + + #define PSA_KEY_TYPE_SLH_DSA_PUBLIC_KEY(set) \ + ((psa_key_type_t) (0x4180 | ((set) & 0x007f))) + #define PSA_KEY_TYPE_SPAKE2P_GET_FAMILY(type) \ ((psa_ecc_family_t) ((type) & 0x007f)) diff --git a/doc/crypto/conf.py b/doc/crypto/conf.py index cf714560..1f1cabfa 100644 --- a/doc/crypto/conf.py +++ b/doc/crypto/conf.py @@ -94,7 +94,9 @@ # 'appendix' : just before the appendices # 'chapter' : before every chapter # Default to 'appendix' - #'page_break': 'chapter' + 'page_break': 'chapter', + + 'prolog_files': ['/substitutions'], } # absolute or relative path to the psa_spec material from this file diff --git a/doc/crypto/figure/encoding/slh_dsa_key.json b/doc/crypto/figure/encoding/slh_dsa_key.json new file mode 100644 index 00000000..7cb8d7bd --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.json @@ -0,0 +1,18 @@ +{ + "reg": [ + { "name": "P", "bits": 1 }, + { "name": "FAMILY", "bits": 6 }, + { "name": "3", "bits": 5 }, + { "name": "PAIR", "bits": 2 }, + { "name": "1", "bits": 1 }, + { "name": "0", "bits": 1 } + ], + "config": { + "lanes": 1, + "fontfamily": "lato", + "fontsize": 11, + "bits": 16, + "vspace": 52, + "hspace": 300 + } +} diff --git a/doc/crypto/figure/encoding/slh_dsa_key.json.license b/doc/crypto/figure/encoding/slh_dsa_key.json.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.json.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/slh_dsa_key.pdf b/doc/crypto/figure/encoding/slh_dsa_key.pdf new file mode 100644 index 0000000000000000000000000000000000000000..9da4f4376ad899e8f6e8e9040108002b03108855 GIT binary patch literal 6866 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 +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/figure/encoding/slh_dsa_key.svg b/doc/crypto/figure/encoding/slh_dsa_key.svg new file mode 100644 index 00000000..342bf210 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.svg @@ -0,0 +1,2 @@ + +01671112131415PFAMILY3PAIR10 \ No newline at end of file diff --git a/doc/crypto/figure/encoding/slh_dsa_key.svg.license b/doc/crypto/figure/encoding/slh_dsa_key.svg.license new file mode 100644 index 00000000..a4671b12 --- /dev/null +++ b/doc/crypto/figure/encoding/slh_dsa_key.svg.license @@ -0,0 +1,2 @@ +SPDX-FileCopyrightText: Copyright 2024 Arm Limited and/or its affiliates +SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license diff --git a/doc/crypto/overview/intro.rst b/doc/crypto/overview/intro.rst index 22dcf0e4..4b4f8f77 100644 --- a/doc/crypto/overview/intro.rst +++ b/doc/crypto/overview/intro.rst @@ -1,4 +1,4 @@ -.. SPDX-FileCopyrightText: Copyright 2018-2025 Arm Limited and/or its affiliates +.. SPDX-FileCopyrightText: Copyright 2018-2026 Arm Limited and/or its affiliates .. SPDX-License-Identifier: CC-BY-SA-4.0 AND LicenseRef-Patent-license Introduction @@ -26,10 +26,6 @@ This document includes: * General considerations for implementers of this specification, and for applications that use the interface defined in this specification. See :secref:`implementation-considerations` and :secref:`usage-considerations`. * A detailed definition of the API. See :secref:`library-management`, :secref:`key-management`, and :secref:`crypto-operations`. -:cite-title:`PSA-PQC` is a companion document for version |docversion| of this specification. -`[PSA-PQC]` defines an API for :term:`Post-Quantum Cryptography` (PQC) algorithms. -The PQC API is now at FINAL status, and will be included in a future version of the |API| specification. - In future, companion documents will define *profiles* for this specification. A profile is a minimum mandatory subset of the interface that a compliant implementation must provide. diff --git a/doc/crypto/substitutions b/doc/crypto/substitutions new file mode 100644 index 00000000..7a1b48df --- /dev/null +++ b/doc/crypto/substitutions @@ -0,0 +1 @@ +.. |XMSS^MT| replace:: XMSS\ :sup:`MT`