diff --git a/doc/ext-pqc/about/references b/doc/ext-pqc/about/references index a213907d..3ca47af8 100644 --- a/doc/ext-pqc/about/references +++ b/doc/ext-pqc/about/references @@ -89,3 +89,27 @@ :author: IETF :publication: June 2025 :url: tools.ietf.org/html/rfc9802 + +.. reference:: SM3-draft + :title: The SM3 Cryptographic Hash Function (Draft 02) + :author: Sean Shen, XiaoDong Lee, Ronald Henry Tse, Wong Wai Kit, Paul Yang + :publication: July 2018 + :url: datatracker.ietf.org/doc/html/draft-sca-cfrg-sm3-02 + +.. reference:: RFC9688 + :title: Use of the SHA3 One-Way Hash Functions in the Cryptographic Message Syntax (CMS) + :author: IETF + :publication: November 2024 + :url: tools.ietf.org/html/rfc9688.html + +.. reference:: RFC8017 + :title: PKCS #1: RSA Cryptography Specifications Version 2.2 + :author: IETF + :publication: November 2016 + :url: tools.ietf.org/html/rfc8017.html + +.. 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/ext-pqc/api/mldsa.rst b/doc/ext-pqc/api/mldsa.rst index 68a73993..bcd8e4d2 100644 --- a/doc/ext-pqc/api/mldsa.rst +++ b/doc/ext-pqc/api/mldsa.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-pqc @@ -181,6 +181,27 @@ The pre-hashed signature computation *HashML-DSA* generates distinct signatures 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 @@ -289,6 +310,8 @@ Context values are arbitrary strings between zero and 255 bytes in length. .. 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 `_. @@ -348,6 +371,8 @@ Context values are arbitrary strings between zero and 255 bytes in length. .. 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:: diff --git a/doc/ext-pqc/api/slhdsa.rst b/doc/ext-pqc/api/slhdsa.rst index 9c4fc6f5..a746a793 100644 --- a/doc/ext-pqc/api/slhdsa.rst +++ b/doc/ext-pqc/api/slhdsa.rst @@ -305,6 +305,27 @@ The pre-hashed signature computation *HashSLH-DSA* generates distinct signatures An SLH-DSA signature can only be verified with an SLH-DSA algorithm. A HashSLH-DSA signature can only be verified with a HashSLH-DSA algorithm. +:numref:`tab-slh-dsa-oid` lists the hash algorithm OIDs to use with the HashSLH-DSA algorithm. +Note that for HashML-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 @@ -413,6 +434,8 @@ Context values are arbitrary strings between zero and 255 bytes in length. .. 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 `_. @@ -472,6 +495,8 @@ Context values are arbitrary strings between zero and 255 bytes in length. .. 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:: diff --git a/doc/ext-pqc/appendix/history.rst b/doc/ext-pqc/appendix/history.rst index 58af63fb..c4f24b91 100644 --- a/doc/ext-pqc/appendix/history.rst +++ b/doc/ext-pqc/appendix/history.rst @@ -12,6 +12,8 @@ Changes between *Final 0* and *Final 1* .. rubric:: Clarifications and fixes * Updated citations for ML-DSA and SLH-DSA key formats. +* Provided a table of hash algorithm OIDs for use with the HashML-DSA and HashSLH-DSA algorithms. + See :secref:`slh-dsa` and :secref:`ml-dsa`. Changes between *Beta 3* and *Final 0* --------------------------------------