Merge pull request #232 from sehlen-bsi/backport/from_release_3.5.0_b…

…ranch

Persistent Changes from Release 3.5.0

.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']:

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 |
+   +---------+---------+--------------------------------------------------------------+------------+

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',
@@ -54,6 +55,7 @@ def additional_modules():
         'ffi',
         'frodokem',
         'frodokem_aes',
+        'hss_lms',
         'kyber_90s',
         'kyber',
         'pkcs11',

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``, ``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:
@@ -150,65 +150,69 @@ 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
+     - kmac
      - kyber
-     - kyber_90s
+   * - kyber_90s
      - kyber_common
-   * - locking_allocator
-     - mac
+     - kyber_round3
+     - locking_allocator
+   * - mac
      - mdx_hash
      - mem_pool
-   * - mgf1
-     - mode_pad
+     - mgf1
+   * - mode_pad
      - modes
      - mp
-   * - numbertheory
-     - pbkdf
+     - numbertheory
+   * - pbkdf
      - pem
      - pk_pad
-   * - pkcs11
-     - poly_dbl
+     - pkcs11
+   * - poly_dbl
      - prf_tls
      - processor_rng
-   * - pubkey
-     - rdseed
+     - pubkey
+   * - rdseed
      - rng
      - rsa
-   * - sha1
-     - sha1_armv8
+     - sha1
+   * - sha1_armv8
      - sha1_sse2
      - sha1_x86
-   * - sha2_32
-     - sha2_32_armv8
+     - sha2_32
+   * - sha2_32_armv8
      - sha2_32_bmi2
      - sha2_32_x86
-   * - sha2_64
-     - sha2_64_armv8
+     - sha2_64
+   * - sha2_64_armv8
      - sha2_64_bmi2
      - sha3
-   * - shake
-     - shake_xof
+     - shake
+   * - shake_xof
      - simd
      - socket
-   * - sp800_108
-     - sp800_56c
+     - sp800_108
+   * - sp800_56c
      - sphincsplus_common
      - sphincsplus_sha2
-   * - sphincsplus_shake
-     - stateful_rng
+     - sphincsplus_shake
+   * - stateful_rng
      - stream
      - system_rng
-   * - tls
-     - tls12
+     - tls
+   * - tls12
      - tls13
      - tls13_pqc
-   * - tls_cbc
+     - tls_cbc
+   * - tree_hash
      - trunc_hash
      - utils
      - x509

docs/cryptodoc/src/00_01_changelog.rst

@@ -155,9 +155,20 @@ 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   |            |
+   |         |          | - Mention the existing KMAC implementation  |            |
+   |         |          | - Adaptions of X.509 path validation        |            |
+   |         |          | - Minor updates on ECC details              |            |
    +---------+----------+---------------------------------------------+------------+

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.

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**

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.

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