From 188f017d6ae57b1a2507dca8d3107f94d92218c0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 10:51:35 +0200 Subject: [PATCH 1/8] Update changelogs in documents --- docs/audit_method/src/00_01_changelog.rst | 4 ++++ docs/cryptodoc/src/00_01_changelog.rst | 11 ++++++++++- 2 files changed, 14 insertions(+), 1 deletion(-) diff --git a/docs/audit_method/src/00_01_changelog.rst b/docs/audit_method/src/00_01_changelog.rst index 4188c8ab..7b769c51 100644 --- a/docs/audit_method/src/00_01_changelog.rst +++ b/docs/audit_method/src/00_01_changelog.rst @@ -43,3 +43,7 @@ +---------+---------+--------------------------------------------------------------+------------+ | 3.3.0 | | - Keine signifikanten Änderungen | 08.01.2024 | +---------+---------+--------------------------------------------------------------+------------+ + | 3.4.0 | | - Keine signifikanten Änderungen | 08.04.2024 | + +---------+---------+--------------------------------------------------------------+------------+ + | 3.5.0 | | - Keine signifikanten Änderungen | 18.07.2024 | + +---------+---------+--------------------------------------------------------------+------------+ diff --git a/docs/cryptodoc/src/00_01_changelog.rst b/docs/cryptodoc/src/00_01_changelog.rst index 754a1dfb..c1b00747 100644 --- a/docs/cryptodoc/src/00_01_changelog.rst +++ b/docs/cryptodoc/src/00_01_changelog.rst @@ -155,9 +155,18 @@ Changelog | | | - SHA-512 based on dedicated instructions | | | | | on ARM v8.2 | | +---------+----------+---------------------------------------------+------------+ - | 3.5.0 | FA, PL | Update to 3.5.0: | TBD | + | 3.4.0 | FA, RM | Update to 3.4.0: | 2024-04-08 | | | | | | + | | | - Detailed explaination of counter-measures | | + | | | against KyberSlash side-channel attack | | + | | | - X.509 path validation may optionally | | + | | | ignore the validity interval of a trusted | | + | | | self-signed root certificate | | + +---------+----------+---------------------------------------------+------------+ + | 3.5.0 | FA, PL, | Update to 3.5.0: | 2024-07-18 | + | | RM | | | | | | - New PQC algorithms | | | | | - HSS/LMS | | | | | - NIST SP800-56Cr2 One-Step KDM with KMAC | | + | | | - Minor updates on ECC details | | +---------+----------+---------------------------------------------+------------+ From 5cd0f9463487c1596a279e8b1d4e7f71a1694b4b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Mon, 22 Jul 2024 10:57:18 +0200 Subject: [PATCH 2/8] Update list of audited modules --- .../scripts/audited_modules_list.py | 1 + docs/audit_report/src/00_09_introduction.rst | 74 ++++++++++--------- 2 files changed, 40 insertions(+), 35 deletions(-) mode change 100644 => 100755 docs/audit_report/scripts/audited_modules_list.py diff --git a/docs/audit_report/scripts/audited_modules_list.py b/docs/audit_report/scripts/audited_modules_list.py old mode 100644 new mode 100755 index 4bffca4b..cd425254 --- a/docs/audit_report/scripts/audited_modules_list.py +++ b/docs/audit_report/scripts/audited_modules_list.py @@ -54,6 +54,7 @@ def additional_modules(): 'ffi', 'frodokem', 'frodokem_aes', + 'hss_lms', 'kyber_90s', 'kyber', 'pkcs11', diff --git a/docs/audit_report/src/00_09_introduction.rst b/docs/audit_report/src/00_09_introduction.rst index d436cb77..acc2afbb 100644 --- a/docs/audit_report/src/00_09_introduction.rst +++ b/docs/audit_report/src/00_09_introduction.rst @@ -56,8 +56,8 @@ dependencies are in the scope of this document. Additionally, we review the following modules and its dependencies: ``certstor_flatfile``, ``certstor_sqlite3``, ``certstor_system_macos``, ``certstor_system_windows``, ``certstor_system``, ``dilithium_aes``, ``dilithium``, ``frodokem``, -``frodokem_aes``, ``ffi``, ``kyber_90s``, ``kyber``, ``pkcs11``, ``sha1_armv8``, -``sha1_sse2``, ``sha1_x86``, ``shake``, ``sphincsplus_sha2``, +``frodokem_aes``, ``hss_lms``, ``ffi``, ``kyber_90s``, ``kyber``, ``pkcs11``, +``sha1_armv8``, ``sha1_sse2``, ``sha1_x86``, ``shake``, ``sphincsplus_sha2``, ``sphincsplus_shake``, ``tls_cbc``, ``tls12``, ``tls13_pqc``, ``tls13``, ``xts``. Patches that don't alter any of the above-mentioned components or relevant modules are considered out-of-scope. @@ -150,72 +150,76 @@ reviewed: - hkdf * - hmac - hmac_drbg + - hss_lms - http_util - - iso9796 - * - kdf + * - iso9796 + - kdf - kdf1_iso18033 - keccak_perm - - keccak_perm_bmi2 - * - keypair + * - keccak_perm_bmi2 + - keypair - kyber - kyber_90s - - kyber_common - * - locking_allocator + * - kyber_common + - kyber_round3 + - locking_allocator - mac - - mdx_hash + * - mdx_hash - mem_pool - * - mgf1 + - mgf1 - mode_pad - - modes + * - modes - mp - * - numbertheory + - numbertheory - pbkdf - - pem + * - pem - pk_pad - * - pkcs11 + - pkcs11 - poly_dbl - - prf_tls + * - prf_tls - processor_rng - * - pubkey + - pubkey - rdseed - - rng + * - rng - rsa - * - sha1 + - sha1 - sha1_armv8 - - sha1_sse2 + * - sha1_sse2 - sha1_x86 - * - sha2_32 + - sha2_32 - sha2_32_armv8 - - sha2_32_bmi2 + * - sha2_32_bmi2 - sha2_32_x86 - * - sha2_64 + - sha2_64 - sha2_64_armv8 - - sha2_64_bmi2 + * - sha2_64_bmi2 - sha3 - * - shake + - shake - shake_xof - - simd + * - simd - socket - * - sp800_108 + - sp800_108 - sp800_56c - - sphincsplus_common + * - sphincsplus_common - sphincsplus_sha2 - * - sphincsplus_shake + - sphincsplus_shake - stateful_rng - - stream + * - stream - system_rng - * - tls + - tls - tls12 - - tls13 + * - tls13 - tls13_pqc - * - tls_cbc - - trunc_hash + - tls_cbc + - tree_hash + * - trunc_hash - utils - x509 - * - xmss - - xof + - xmss + * - xof - xts - + - Here are some notable module changes compared to the last review (Botan |botan_git_base_ref|): From d471132090ba7bf3b96b5a862cd4085e4439505a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 13:19:19 +0200 Subject: [PATCH 3/8] KMAC in the cryptodoc KMAC was initially introduced in Botan 3.2.0 but we missed to mention it in the crypto documentation thus far. --- .../scripts/audited_modules_list.py | 1 + docs/audit_report/src/00_09_introduction.rst | 72 +++++++++--------- docs/cryptodoc/src/00_01_changelog.rst | 1 + docs/cryptodoc/src/03_mac.rst | 30 ++++++++ docs/cryptodoc/src/90_bibliographie.rst | 5 ++ docs/testspec/src/07_mac.rst | 76 +++++++++++++++++++ 6 files changed, 149 insertions(+), 36 deletions(-) diff --git a/docs/audit_report/scripts/audited_modules_list.py b/docs/audit_report/scripts/audited_modules_list.py index cd425254..0fe1148d 100755 --- a/docs/audit_report/scripts/audited_modules_list.py +++ b/docs/audit_report/scripts/audited_modules_list.py @@ -30,6 +30,7 @@ def platform_dependent_modules(): 'ghash_cpu', 'ghash_vperm', 'keccak_perm_bmi2', + 'kmac', 'sha1_armv8', 'sha1_sse2', 'sha1_x86', diff --git a/docs/audit_report/src/00_09_introduction.rst b/docs/audit_report/src/00_09_introduction.rst index acc2afbb..fe9adec7 100644 --- a/docs/audit_report/src/00_09_introduction.rst +++ b/docs/audit_report/src/00_09_introduction.rst @@ -56,11 +56,11 @@ dependencies are in the scope of this document. Additionally, we review the following modules and its dependencies: ``certstor_flatfile``, ``certstor_sqlite3``, ``certstor_system_macos``, ``certstor_system_windows``, ``certstor_system``, ``dilithium_aes``, ``dilithium``, ``frodokem``, -``frodokem_aes``, ``hss_lms``, ``ffi``, ``kyber_90s``, ``kyber``, ``pkcs11``, -``sha1_armv8``, ``sha1_sse2``, ``sha1_x86``, ``shake``, ``sphincsplus_sha2``, -``sphincsplus_shake``, ``tls_cbc``, ``tls12``, ``tls13_pqc``, ``tls13``, -``xts``. Patches that don't alter any of the above-mentioned components or -relevant modules are considered out-of-scope. +``frodokem_aes``, ``hss_lms``, ``ffi``, ``kmac``, ``kyber_90s``, ``kyber``, +``pkcs11``, ``sha1_armv8``, ``sha1_sse2``, ``sha1_x86``, ``shake``, +``sphincsplus_sha2``, ``sphincsplus_shake``, ``tls_cbc``, ``tls12``, +``tls13_pqc``, ``tls13``, ``xts``. Patches that don't alter any of the +above-mentioned components or relevant modules are considered out-of-scope. Below is the full list of modules (from ``src/lib``) whose changes were reviewed: @@ -158,68 +158,68 @@ reviewed: - keccak_perm * - keccak_perm_bmi2 - keypair + - kmac - kyber - - kyber_90s - * - kyber_common + * - kyber_90s + - kyber_common - kyber_round3 - locking_allocator - - mac - * - mdx_hash + * - mac + - mdx_hash - mem_pool - mgf1 - - mode_pad - * - modes + * - mode_pad + - modes - mp - numbertheory - - pbkdf - * - pem + * - pbkdf + - pem - pk_pad - pkcs11 - - poly_dbl - * - prf_tls + * - poly_dbl + - prf_tls - processor_rng - pubkey - - rdseed - * - rng + * - rdseed + - rng - rsa - sha1 - - sha1_armv8 - * - sha1_sse2 + * - sha1_armv8 + - sha1_sse2 - sha1_x86 - sha2_32 - - sha2_32_armv8 - * - sha2_32_bmi2 + * - sha2_32_armv8 + - sha2_32_bmi2 - sha2_32_x86 - sha2_64 - - sha2_64_armv8 - * - sha2_64_bmi2 + * - sha2_64_armv8 + - sha2_64_bmi2 - sha3 - shake - - shake_xof - * - simd + * - shake_xof + - simd - socket - sp800_108 - - sp800_56c - * - sphincsplus_common + * - sp800_56c + - sphincsplus_common - sphincsplus_sha2 - sphincsplus_shake - - stateful_rng - * - stream + * - stateful_rng + - stream - system_rng - tls - - tls12 - * - tls13 + * - tls12 + - tls13 - tls13_pqc - tls_cbc - - tree_hash - * - trunc_hash + * - tree_hash + - trunc_hash - utils - x509 - - xmss - * - xof + * - xmss + - xof - xts - - - Here are some notable module changes compared to the last review (Botan |botan_git_base_ref|): diff --git a/docs/cryptodoc/src/00_01_changelog.rst b/docs/cryptodoc/src/00_01_changelog.rst index c1b00747..3d8e9b4f 100644 --- a/docs/cryptodoc/src/00_01_changelog.rst +++ b/docs/cryptodoc/src/00_01_changelog.rst @@ -168,5 +168,6 @@ Changelog | | | - New PQC algorithms | | | | | - HSS/LMS | | | | | - NIST SP800-56Cr2 One-Step KDM with KMAC | | + | | | - Mention the existing KMAC implementation | | | | | - Minor updates on ECC details | | +---------+----------+---------------------------------------------+------------+ diff --git a/docs/cryptodoc/src/03_mac.rst b/docs/cryptodoc/src/03_mac.rst index 186150c2..d841f385 100644 --- a/docs/cryptodoc/src/03_mac.rst +++ b/docs/cryptodoc/src/03_mac.rst @@ -80,3 +80,33 @@ that the developer sets the nonce before each new GMAC computation. **Remark:** GMAC is generally used in AES-GCM. For different encryption mechanisms HMAC and CMAC should be used in favor of GMAC. + +KMAC +---- + +KMAC is a message authentication code based on the Keccak sponge construction, +and more specifically, on the cSHAKE function. Both are defined in [SP800-185]_. + +Botan implements both KMAC-128 and KMAC-256 with a variable (user-defined) +output length. Note that the output length must be defined at the beginning, +Botan currently does not implement the XOF variants of KMAC. + +KMAC is implemented in :srcref:`src/lib/mac/kmac/kmac.cpp`, and cSHAKE can be +found in :srcref:`src/lib/xof/cshake_xof/cshake_xof.cpp`. Note that cSHAKE is +an implementation detail that is not exposed to the library user. + +- ``KMAC128(output_bits)`` / ``KMAC256(output_bits)``: Constructs a KMAC object + that will produce a MAC tag of ``output_bits`` length (divisible by 8). +- ``set_key(key)``: It initializes KMAC computation with a symmetric key. + The key length is not fixed. Botan supports a maximum key length of 192 bytes. +- ``start_msg(nonce)``: It initializes the KMAC computation with an optional + nonce that is absorbed into the Keccak sponge with a padding first. +- ``add_data(buffer)``: It takes the buffer value and updates KMAC's Internal + Keccak sponge state. +- ``final_result(mac)``: It finalizes the KMAC computation and creates + an authentication tag of length ``output_bits``. It fills the provided mac + parameter array with the authentication tag data. + +**Remark:** Botan does not prevent the user from using short keys and/or MAC +tags. It is the responsibility of the library user to select appropriate key +lengths and MAC tag lengths. diff --git a/docs/cryptodoc/src/90_bibliographie.rst b/docs/cryptodoc/src/90_bibliographie.rst index ae226159..c072e2f7 100644 --- a/docs/cryptodoc/src/90_bibliographie.rst +++ b/docs/cryptodoc/src/90_bibliographie.rst @@ -227,6 +227,11 @@ https://csrc.nist.gov/publications/detail/sp/800-208/final, October 2020 +.. [SP800-185] NIST Special Publication 800-185: + "SHA-3 Derived Functions: cSHAKE, KMAC, TupleHash, and ParallelHash" + https://csrc.nist.gov/publications/detail/sp/800-185/final, + December 2016 + .. [SPX-R3] J.-P. Aumasson, D. J. Bernstein, W. Beullens, C. Dobraunig, M. Eichlseder, S. Fluhrer, S.-L. Gazdag, A. Hülsing, P. Kampanakis, S. Kölbl, T. Lange, M. M. Lauridsen, F. Mendel, R. Niederhagen, C. Rechberger, J. Rijneveld, P. Schwabe, B. Westerbaan: "SPHINCS+ Submission to the NIST post-quantum project, v.3.1", NIST PQC Challenge Round 3 Submission, 2021, diff --git a/docs/testspec/src/07_mac.rst b/docs/testspec/src/07_mac.rst index 3dc2a152..93458de9 100644 --- a/docs/testspec/src/07_mac.rst +++ b/docs/testspec/src/07_mac.rst @@ -331,3 +331,79 @@ The test vectors were generated with Bouncy Castle Crypto 1.54. | | functions on the GMAC with these arrays. Calculate the tag and | | | compare it with the expected output value *Out* | +----------------------+--------------------------------------------------------------------------+ + +KMAC +---- + +KMAC is tested with the following constraints: + +- Number of test cases: 6 + +- Key: 256 bits + +- Nonce: varying length + + - Range: None - 168 bits + +- In: varying length + + - Range: 32 bits – 1600 bits + - Extreme values: 896 bits + +- Out: varying length + + - 256 bits for KMAC-128 + - 512 bits for KMAC-256 + +The following table shows an example test case with one test vector. All +test vectors are listed in :srcref:`src/tests/data/mac/kmac.vec`. + +The tests are taken from NIST's `KMAC_samples.pdf `_. + +.. table:: + :class: longtable + :widths: 20 80 + + +----------------------+--------------------------------------------------------------------------+ + | **Test Case No.:** | MAC-KMAC-1 | + +======================+==========================================================================+ + | **Type:** | Positive Test | + +----------------------+--------------------------------------------------------------------------+ + | **Description:** | Combined unit and known answer test that checks that reset works | + | | correctly and calculates the GMAC tag on a test message | + +----------------------+--------------------------------------------------------------------------+ + | **Preconditions:** | None | + +----------------------+--------------------------------------------------------------------------+ + | **Input Values:** | Algorithm = KMAC-128 | + | | | + | | Nonce = 0x4D7920546167676564204170706C69636174696F6E (168 bits) | + | | | + | | Key = 0x404142434445464748494A4B4C4D4E4F505152535455565758595A5B5C5D5E5F | + | | (128 bits) | + | | | + | | In = 0x0001020...C4C5C6C7 (1600 bits) | + +----------------------+--------------------------------------------------------------------------+ + | **Expected Output:** | Out = 0x1F5B4E6CCA02209E0DCB5CA635B89A15E271ECC760071DFD805FAA38F9729230 | + | | (256 bits) | + +----------------------+--------------------------------------------------------------------------+ + | **Steps:** | #. Create the KMAC object | + | | | + | | #. Test the name of the KMAC | + | | | + | | #. Set the key *Key* | + | | | + | | #. Set the nonce *Nonce* | + | | | + | | #. Input *In* into the KMAC, calculate the tag and compare it with the | + | | expected output value *Out* | + | | | + | | #. Reset the KMAC | + | | | + | | #. Set the key *Key* | + | | | + | | #. Set the nonce *Nonce* | + | | | + | | #. Split the input string *IN* into three arrays and invoke three update | + | | functions on the KMAC with these arrays. Calculate the tag and | + | | compare it with the expected output value *Out* | + +----------------------+--------------------------------------------------------------------------+ From 62203a4f63a1ab8e660fa02d0d9d94baf7267fda Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 13:31:59 +0200 Subject: [PATCH 4/8] DLIES is deprecated --- docs/cryptodoc/src/06_hpke.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/cryptodoc/src/06_hpke.rst b/docs/cryptodoc/src/06_hpke.rst index 5ea5c8fd..bf781709 100644 --- a/docs/cryptodoc/src/06_hpke.rst +++ b/docs/cryptodoc/src/06_hpke.rst @@ -11,6 +11,11 @@ and standardized by the IEEE, ANSI and ISO. DLIES ----- +.. warning:: + + As of Botan 3.5.0 the DLIES implementation is considered deprecated and + will be removed in a future release. + The Discrete Logarithm Integrated Encryption Scheme (DLIES) utilizes the Diffie-Hellman key exchange as the asymmetric component of the scheme. The symmetric cipher and MAC can be chosen. Botan implements the DLIES From 75e76fc242740af3a3c5b0b8d9f3672bfdbc618c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 13:32:22 +0200 Subject: [PATCH 5/8] Remove OCSP vulnerability notice --- docs/cryptodoc/src/09_x509.rst | 26 ++++---------------------- 1 file changed, 4 insertions(+), 22 deletions(-) diff --git a/docs/cryptodoc/src/09_x509.rst b/docs/cryptodoc/src/09_x509.rst index c5b36348..edc3efc8 100644 --- a/docs/cryptodoc/src/09_x509.rst +++ b/docs/cryptodoc/src/09_x509.rst @@ -78,10 +78,6 @@ recommendations of [TR-02103]_. Some extended validation recommendations are not implemented in the library but can be manually added at application level, if needed. -.. warning:: OCSP responses are currently vulnerable to spoofing and must not be - used for certificate revocation status checks. See :ref:`x509/check_ocsp` for - further details on this vulnerability. - Detailed Description of Path Validation Algorithms -------------------------------------------------- @@ -741,28 +737,14 @@ certificate chain. It returns a list of sets of certificate status codes, each entry in the list contains the status codes for each certificate in the chain. -**Vulnerability:** Botan 3.0.0-alpha1 and previous versions contained a bug in -the OCSP response validation where the authenticity of a spoofed response was not -properly checked. That allowed an attacker to forge OCSP responses for arbitrary -CAs that were considered authentic. That alone had the potential for DOS -attacks. Provided the attacker was in possession of a compromised subject -certificate, they would have been able to circumvent revocation checks and (keep) -impersonating the legitimate certificate owner (if no additional CRL-based -checks are performed). - -This vulnerability was assigned CVE-2022-43705. For further details, please refer -to the `associated security advisory in Botan's GitHub repository -`_ or -the vulnerability description document provided along with this report. - -**Conclusion:** With `the given patch `_ -applied, Botan is no longer vulnerable to the described issue. - Full compliance with the extended OCSP validation rules layed out in [TR-02103]_ requires that authorized OCSP responder certificates that in-turn contain an OCSP responder in its AuthorityInformationAccess extension to be "recursively" checked for their revocation status. This functionality is currently not implemented in -Botan. +Botan [#ocsp_extension]_. + +.. [#ocsp_extension] See `GitHub #3124 `_ + where any potential improvement to this functionality is discussed. .. admonition:: ``check_ocsp()`` From de943e1eb29ea4c8f17e9252131591c27c1cb5d1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 13:50:44 +0200 Subject: [PATCH 6/8] reflect X.509 adaptions in crypto documentation --- docs/cryptodoc/src/00_01_changelog.rst | 1 + docs/cryptodoc/src/09_x509.rst | 80 ++++++++++++++------------ 2 files changed, 44 insertions(+), 37 deletions(-) diff --git a/docs/cryptodoc/src/00_01_changelog.rst b/docs/cryptodoc/src/00_01_changelog.rst index 3d8e9b4f..e4b28f78 100644 --- a/docs/cryptodoc/src/00_01_changelog.rst +++ b/docs/cryptodoc/src/00_01_changelog.rst @@ -169,5 +169,6 @@ Changelog | | | - HSS/LMS | | | | | - NIST SP800-56Cr2 One-Step KDM with KMAC | | | | | - Mention the existing KMAC implementation | | + | | | - Adaptions of X.509 path validation | | | | | - Minor updates on ECC details | | +---------+----------+---------------------------------------------+------------+ diff --git a/docs/cryptodoc/src/09_x509.rst b/docs/cryptodoc/src/09_x509.rst index edc3efc8..cc87f610 100644 --- a/docs/cryptodoc/src/09_x509.rst +++ b/docs/cryptodoc/src/09_x509.rst @@ -379,6 +379,10 @@ period, signatures and extensions, e.g., key usage. It returns a list of sets of certificate status codes, each entry in the list contains the status codes for each certificate in the chain. +First and foremost this function checks all signatures in the certificate +chain. If any signature cannot be verified, no further checks are made, +as no guarantees can be given about the validity of the certificates anyway. + Note that this function does not validate any revocation information. See :ref:`x509/check_crl`, :ref: `x509/check_ocsp` and :ref:`x509/merge_revocation_status` for details on revocation checks. @@ -413,20 +417,43 @@ validation of the CertificatePolicies extension. Steps: - a) If ``hostname`` is given and ``cert_path[0]`` does not contain a match + a) For ``i = 0...n-1`` in ``cert_path`` do: + + 1. If ``subject.signature_algorithm().oid`` is unknown then do Append + SIGNATURE_ALGORITHM_UNKNOWN to ``cert_status[i]`` + + 2. If the ``issuer`` public key cannot be loaded from the ``issuer`` + certificate, then do Append CERT_PUBKEY_INVALID to + ``cert_status[i]`` and continue with step l) + + 3. If ``issuer``'s public key strength < + ``restrictions.minimum_key_strength()`` then do Append SIGNATURE_METHOD_TOO_WEAK to + ``cert_status[i]`` + + 4. If the signature on ``subject`` can not be verified using + ``issuer``'s public key, Append the corresponding error to + ``cert_status[i]`` + + 5. If (``restrictions.trusted_hashes()`` is not empty AND + ``at_self_signed_root = false`` AND the hash function used in + ``subject`` IS NOT IN ``restrictions.trusted_hashes()``) then do + Append UNTRUSTED_HASH to ``cert_status[i]`` // ignore untrusted hashes + on self-signed root certs + + b) If ``hostname`` is given and ``cert_path[0]`` does not contain a match for ``hostname`` according to [RFC6125]_, Append Certificate_Status_Codes::CERT_NAME_NOMATCH to ``cert_status[0]`` // see function ``matches_dns_name()`` below - b) If ``usage`` is given and ``cert_path[0]`` does not contain key usage and + c) If ``usage`` is given and ``cert_path[0]`` does not contain key usage and extended key usage bits according to [RFC5280]_, sec. 4.2.1.12, Append INVALID_USAGE to ``cert_status[0]`` - c) If ``cert_path[0]`` has basic constraints with a set cA bit, and + d) If ``cert_path[0]`` has basic constraints with a set cA bit, and keyCertSign is not set, then, according to [RFC5280]_, sec. 4.2.1.9, Append INVALID_USAGE to ``cert_status[0]`` - d) For ``i = 0...n-1`` in ``cert_path`` do: + e) For ``i = 0...n-1`` in ``cert_path`` do: 1. Set ``at_self_signed_root = (i == cert_path.size() - 1)`` // last certificate in the chain? @@ -464,46 +491,25 @@ validation of the CertificatePolicies extension. ``cert_path`` contains more than one certificate, Append CA_CERT_NOT_FOR_CERT_ISSUER to ``cert_status[i]`` - 11. If ``subject.signature_algorithm().oid`` is unknown then do Append - SIGNATURE_ALGORITHM_UNKNOWN to ``cert_status[i]`` - - 12. If the ``issuer`` public key cannot be loaded from the ``issuer`` - certificate, then do Append CERT_PUBKEY_INVALID to - ``cert_status[i]`` and continue with step l) - - 13. If the signature on ``subject`` can not be verified using - ``issuer``'s public key, Append the corresponding error to - ``cert_status[i]`` - - 14. If ``issuer``'s public key strength < - ``restrictions.minimum_key_strength()`` then do Append SIGNATURE_METHOD_TOO_WEAK to - ``cert_status[i]`` - - 15. If (``restrictions.trusted_hashes()`` is not empty AND - ``at_self_signed_root = false`` AND the hash function used in - ``subject`` IS NOT IN ``restrictions.trusted_hashes()``) then do - Append UNTRUSTED_HASH to ``cert_status[i]`` // ignore untrusted hashes - on self-signed root certs - - 16. If (``x509_version`` of ``subject`` is 1 AND + 11. If (``x509_version`` of ``subject`` is 1 AND ``subject`` contains ``v2_issuer_key_id`` OR ``v2_subject_key_id``) then do Append V2_IDENTIFIERS_IN_V1_CERT to ``cert_status[i]``. - 17. If ``subjet.cert_version() < 3`` and ``subject.v3_extensions()`` is + 12. If ``subjet.cert_version() < 3`` and ``subject.v3_extensions()`` is not empty then do Append EXT_IN_V1_V2_CERT to ``cert_status[i]`` - 18. Check all other certificate extensions ``ext`` in ``subject``: + 13. Check all other certificate extensions ``ext`` in ``subject``: i. ``ext.validate(subject, issuer, cert_path, cert_status, i)`` // ``ext`` tries validating itself and modifies ``cert_status`` as appropriate - 19. If there ``subject.extensions()`` contains two extensions with + 14. If there ``subject.extensions()`` contains two extensions with identical OIDs then do Append DUPLICATE_CERT_EXTENSION - e) set ``max_path_length = n`` // path length check + f) set ``max_path_length = n`` // path length check - f) From ``i := n - 1`` downto ``1`` + g) From ``i := n - 1`` downto ``1`` 1. If ``cert_path[i].subject_dn() != cert_path[i].issuer_dn()`` then do @@ -514,7 +520,7 @@ validation of the CertificatePolicies extension. 2. If ``cert_path[i]`` has a path limit then do Set ``max_path_len = min(max_path_len, cert_path[i].path_limit())`` - e) Return ``cert_status`` + h) Return ``cert_status`` Function host_wildcard_match() ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -623,9 +629,9 @@ name, according to [RFC6125]_. 2. Set ``issued_names`` = all entries in the *DNS* field of the SubjectAlternativeName extension or subject DN - 3. If (``issued_names`` is empty) then do set ``issued_names`` = all entries - in the *CN* field of subject DN // fall back to CN only if no DNS - names are set, RFC 6125 sec. 6.4.4 + 3. If no subject alternative names extension is available then do set + ``issued_names`` = all entries in the *CN* field of subject DN // fall + back to CN only if no DNS names are set, RFC 6125 sec. 6.4.4 4. For ``i=0..n`` do: @@ -716,8 +722,8 @@ of [TR-02103]_ for handling certificate revocation checks using CRLs. h) Append VALID_CRL_CHECKED to ``cert_status[i]`` i) If crls[i] lists subject as REVOKED, Append CERT_IS_REVOKED to ``cert_status[i]`` - j) If ``subject.crl_distribution_point != - crls[i].crl_issuing_distribution_point()`` then do Append + j) If ``subject.crl_distribution_point`` not in + ``crls[i].issuing_distribution_points()`` then do Append NO_MATCHING_CRLDP to ``cert_status[i]`` k) If ``crls[i]`` contains an unknown critical extension then do Append CERT_IS_REVOKED to ``cert_status[i]`` // according From f6edbe87ebcbd21027e558e30f817ae593e09a48 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 14:50:52 +0200 Subject: [PATCH 7/8] Mention the Limbo X.509 tests in the testspec --- .github/scripts/ci_build.py | 2 ++ docs/testspec/src/17_x509.rst | 15 +++++++++++++++ 2 files changed, 17 insertions(+) diff --git a/.github/scripts/ci_build.py b/.github/scripts/ci_build.py index 55c1517b..33632e89 100644 --- a/.github/scripts/ci_build.py +++ b/.github/scripts/ci_build.py @@ -123,6 +123,8 @@ def determine_flags(target, target_os, target_cc, ccache, enable_modules += ['dilithium','dilithium_aes'] enable_modules += ['sphincsplus_sha2','sphincsplus_shake'] enable_modules += ['frodokem','frodokem_aes'] + enable_modules += ['hss_lms'] + enable_modules += ['kmac'] flags += ['--module-policy=bsi', '--enable-modules=%s' % ','.join(enable_modules)] if target in ['pdf_docs']: diff --git a/docs/testspec/src/17_x509.rst b/docs/testspec/src/17_x509.rst index 7d8f118a..222bd717 100644 --- a/docs/testspec/src/17_x509.rst +++ b/docs/testspec/src/17_x509.rst @@ -438,3 +438,18 @@ signature validation) and also using online tests for randombit.net. Online tests are only executed if BOTAN_HAS_ONLINE_REVOCATION_CHECKS is set. The tests are implemented in :srcref:`src/tests/test_ocsp.cpp`. All test data can be found in :srcref:`src/tests/data/x509/ocsp`. + +Limbo X.509 Tests +----------------- + +Limbo [#limbo_url]_ is a testsuite for evaluating X.509 path validation +implementations that is maintained by "Trail of Bits". It contains several +thousand certificate validation test cases. + +Botan's CI is running the entire Limbo test harness via the library's python +binding to verify proper path building and validation. Less than 1% of the +tests are either ignored, disabled or produce a different result than expected. +See :srcref:`src/scripts/run_limbo_tests.py:18|tests_that_succeed_unexpectedly` +for the full details of the irregular test results. + +.. [#limbo_url] Limbo X.509 test suite: https://x509-limbo.com/ From b69d9afbd730695357b543003b3d8d97d2771c26 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Meusel?= Date: Thu, 18 Jul 2024 15:13:06 +0200 Subject: [PATCH 8/8] minor kyber/dilithium adaptions --- docs/cryptodoc/src/05_08_dilithium.rst | 5 +++++ docs/cryptodoc/src/05_09_kyber.rst | 13 +++++-------- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/docs/cryptodoc/src/05_08_dilithium.rst b/docs/cryptodoc/src/05_08_dilithium.rst index 13932e37..1d50a746 100644 --- a/docs/cryptodoc/src/05_08_dilithium.rst +++ b/docs/cryptodoc/src/05_08_dilithium.rst @@ -77,6 +77,11 @@ Also like Kyber, Dilithium additionally supports different instantiations of sym These are also provided by the mode and result in the "modern" and "AES" versions. An "AES" version is identified via the ``_aes`` suffix in the mode string. +.. warning:: + + The AES-based variants of Dilithium are deprecated and will be removed in a future release. + NIST decided not to standardize those variants in their final ML-DSA standard. + .. _pubkey_key_generation/dilithium/polynomials: **Polynomial Operations** diff --git a/docs/cryptodoc/src/05_09_kyber.rst b/docs/cryptodoc/src/05_09_kyber.rst index 0b70324a..b6e37e1d 100644 --- a/docs/cryptodoc/src/05_09_kyber.rst +++ b/docs/cryptodoc/src/05_09_kyber.rst @@ -3,14 +3,6 @@ Kyber ===== -.. todo:: - - This documentation is outdated (and potentially too detailed). - It should be updated as soon as those pull requests are merged: - - * https://github.com/randombit/botan/pull/4024 - - Until then, I've removed some of the source links to pass CI. Botan implements the CRYSTALS-Kyber KEM in :srcref:`src/lib/pubkey/kyber/`. The implementation is based on the NIST round 3 specification [Kyber-R3]_. @@ -110,6 +102,11 @@ For each mode, the ``KyberConstants`` class contains the corresponding set of pa | Kyber 90s | AES-256-CTR | SHA-256 | SHA512 | AES-256-CTR | SHA-256 | +-------------------+--------------+----------+-----------+--------------+------------+ +.. warning:: + + The 90s-variants of Kyber that are using AES and SHA-2 are deprecated and will be removed in a future release. + NIST decided not to standardize those variants in their final ML-KEM standard. + Kyber itself is implemented in :srcref:`[src/lib/pubkey/kyber]/kyber_common/kyber.cpp`. Basic representations and operations on polynomials, polynomial vectors, and polynomial matrices are given via the ``Polynomial``, ``PolynomialVector``, and ``PolynomialMatrix`` classes (see :srcref:`[src/lib/pubkey/kyber/kyber_common]/kyber_structures.h`), respectively. ``Polynomial`` and ``PolynomialVector`` support member functions ``.ntt()`` and ``.invntt()`` for the number-theoretic transform (NTT; see more details in Section 1.1 of [Kyber-R3]_) and fast multiplication in the NTT domain.