Release: Botan 3.6.1

config/botan.env

@@ -22,7 +22,7 @@ BOTAN_MAIN_BRANCH=master
 # This must be a semver version string and will be printed (among other
 # things) as the reference version in the final document outputs. As such, it
 # might be a preliminary version that is still in development.
-BOTAN_VERSION=3.6.1
+BOTAN_VERSION=3.6.1-draft1
 
 # The concrete Botan repository reference that is currently used in the
 # creation of source-code related document generation. Once a Botan release is

docs/architecture/src/01_architecture.rst

@@ -53,7 +53,7 @@ tests            Test suite and test data
 
 
 The ``lib`` directory has a fine-grained structure into modules and sub-modules.
-Botan's `online documentation <https://botan.randombit.net/doxygen/modules.html>`_ provides a comprehensive overview of those modules and their inter-dependency.
+Botan's `online documentation <https://botan.randombit.net/doxygen/topics.html>`_ provides a comprehensive overview of those modules and their inter-dependency.
 For further details, please see the Handbook section 18.1 or the online documentation:
 `Notes for New Contributers <https://botan.randombit.net/handbook/dev_ref/contributing.html#library-layout>`_
 

docs/audit_method/src/00_01_changelog.rst

@@ -47,3 +47,5 @@
    +---------+---------+--------------------------------------------------------------+------------+
    | 3.5.0   |         | - Keine signifikanten Änderungen                             | 18.07.2024 |
    +---------+---------+--------------------------------------------------------------+------------+
+   | 3.6.1   |         | - Keine signifikanten Änderungen                             | 29.10.2024 |
+   +---------+---------+--------------------------------------------------------------+------------+

docs/audit_method/src/03_sidechannel_analysis.rst

@@ -37,6 +37,7 @@ durchzuführen. Bei der ersten Variante wird Valgrind genutzt. Hierzu reicht es
 Botan mit ``--with-valgrind`` zu konfigurieren, die Bibliothek anschließend zu
 kompilieren und im Anschluss die Testsuite auszuführen. Gefundene Fehler werden
 während der Ausführung der Tests von Valgrind auf die Konsole ausgegeben.
+Weitere Details zu Valgrind finden sich in der Test Spezifikation [TESTSP]_.
 
 Bei der zweiten Variante werden die in AP2 des Projekt 197 entwickelten
 erweiterten Tests genutzt. Diese wurden in das CLI-Tool mit dem Kommando

docs/audit_report/changes/topics/fixes.yml

@@ -1,5 +1,11 @@
 title: Fixes
 
+description: |
+  This section covers patches that address bugs, performance regressions, or
+  other issues that have been identified in the library. Most relevant are
+  patches that reduce the likelihood of compiler optimizations that would
+  potentially cause side channel vulnerabilities in FrodoKEM and Curve25519.
+
 patches:
 # FIX: move() of scoped_cleanup  (@reneme)
 - pr: 4202  # https://github.com/randombit/botan/pull/4202

docs/audit_report/changes/topics/tls.yml

@@ -1,5 +1,10 @@
 title: Transport Layer Security (TLS)
 
+description: |
+  Most notably, the experimental TLS key exchange groups based on Kyber
+  are now deprecated and replaced by two groups based on the ML-KEM-768
+  and ECDH over secp256r1 or Curve25519.
+
 patches:
 # Deprecate 0xFE30 X25519/Kyber512 code point
 #   Author:    @reneme

docs/audit_report/scripts/audited_modules_list.py

@@ -21,6 +21,7 @@ def platform_dependent_modules():
         'aes_ni',
         'aes_power8',
         'aes_vperm',
+        'aes_vaes',
         'argon2_avx2',
         'argon2_ssse3',
         'certstor_sql',
@@ -55,14 +56,16 @@ def additional_modules():
         'frodokem',
         'frodokem_aes',
         'hss_lms',
+        'jitter_rng',
+        'kmac',
         'ml_kem',
         'pcurves_brainpool256r1',
         'pcurves_brainpool384r1',
         'pcurves_brainpool512r1',
         'pcurves_secp256r1',
         'pcurves_secp256k1',
         'pcurves_secp384r1',
-        'pcurves_secp521r1'
+        'pcurves_secp521r1',
         'pkcs11',
         'shake',
         'slh_dsa_sha2',
@@ -71,6 +74,10 @@ def additional_modules():
         'tls12',
         'tls13_pqc',
         'tls13',
+        'tpm2',
+        'tpm2_crypto_backend',
+        'tpm2_rsa',
+        'tpm2_ecc',
         'xts',
     ])
 

docs/audit_report/src/00_00_preface.rst

@@ -22,6 +22,7 @@ audit target revision to establish a new audited revision.
 
 | Fabian Albert (FA), Rohde & Schwarz Cybersecurity
 | René Meusel (RM), Rohde & Schwarz Cybersecurity
+| Amos Treiber (AT), Rohde & Schwarz Cybersecurity
 | Andreas Seelos-Zankl (ASZ), Fraunhofer AISEC
 | Alexander Wagner (AW), Fraunhofer AISEC
 

docs/audit_report/src/00_09_introduction.rst

@@ -54,19 +54,18 @@ components. For the library implementation itself (``src/lib``), all modules
 that are *required* or *available* in the BSI build policy and their
 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``, ``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.
+``certstor_system``, ``ml_dsa``, ``ffi``, ``frodokem``, ``frodokem_aes``,
+``hss_lms``, ``jitter_rng``, ``kmac``, ``ml_kem``, ``pcurves_brainpool256r1``,
+``pcurves_brainpool384r1``, ``pcurves_brainpool512r1``, ``pcurves_secp256r1``,
+``pcurves_secp256k1``, ``pcurves_secp384r1``, ``pcurves_secp521r1``, ``pkcs11``,
+``shake``, ``slh_dsa_sha2``, ``slh_dsa_shake``, ``tls_cbc``, ``tls12``,
+``tls13_pqc``, ``tls13``, ``tpm2``, ``tpm2_crypto_backend``, ``tpm2_rsa``,
+``tpm2_ecc``, ``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:
 
-.. todo:: Update the module list below for the upcoming release
-
 .. For each new document version, the list below should be sanity checked
    and potentially adapted using the script in scripts/audited_modules_list.py
    like so:
@@ -87,9 +86,9 @@ reviewed:
    * - aead
      - aes
      - aes_armv8
-     - aes_crystals_xof
-   * - aes_ni
-     - aes_power8
+     - aes_ni
+   * - aes_power8
+     - aes_vaes
      - aes_vperm
      - argon2
    * - argon2_avx2
@@ -112,25 +111,25 @@ reviewed:
      - certstor_system_windows
      - cmac
      - cpuid
-   * - ctr
+   * - cshake_xof
+     - ctr
      - dh
-     - dilithium
-     - dilithium_aes
-   * - dilithium_common
+     - dilithium_common
+   * - dilithium_shake
      - dl_algo
      - dl_group
-     - dlies
-   * - dsa
-     - dyn_load
+     - dsa
+   * - dyn_load
      - ec_group
      - ecc_key
-   * - ecdh
-     - ecdsa
+     - ecdh
+   * - ecdsa
      - ecgdsa
      - ecies
-   * - eckcdsa
-     - eme_oaep
+     - eckcdsa
+   * - eme_oaep
      - eme_pkcs1
+     - eme_raw
      - emsa_pkcs1
    * - emsa_pssr
      - entropy
@@ -153,57 +152,61 @@ reviewed:
      - hss_lms
      - http_util
    * - iso9796
+     - jitter_rng
      - kdf
      - kdf1_iso18033
-     - keccak_perm
-   * - keccak_perm_bmi2
+   * - keccak_perm
+     - keccak_perm_bmi2
      - keypair
      - kmac
-     - kyber
-   * - kyber_90s
-     - kyber_common
-     - kyber_round3
+   * - kyber_common
      - locking_allocator
-   * - mac
+     - mac
      - mdx_hash
-     - mem_pool
+   * - mem_pool
      - mgf1
+     - ml_dsa
+     - ml_kem
    * - mode_pad
      - modes
      - mp
      - numbertheory
    * - pbkdf
+     - pcurves
      - pem
      - pk_pad
-     - pkcs11
-   * - poly_dbl
+   * - pkcs11
+     - poly_dbl
+     - pqcrystals
      - prf_tls
-     - processor_rng
+   * - processor_rng
      - pubkey
-   * - rdseed
+     - rdseed
      - rng
-     - rsa
+   * - rsa
      - sha1
-   * - sha1_armv8
+     - sha1_armv8
      - sha1_sse2
-     - sha1_x86
+   * - sha1_x86
      - sha2_32
-   * - sha2_32_armv8
+     - sha2_32_armv8
      - sha2_32_bmi2
-     - sha2_32_x86
+   * - sha2_32_x86
      - sha2_64
-   * - sha2_64_armv8
+     - sha2_64_armv8
      - sha2_64_bmi2
-     - sha3
+   * - sha3
      - shake
-   * - shake_xof
+     - shake_xof
      - simd
+   * - slh_dsa_sha2
+     - slh_dsa_shake
      - socket
      - sp800_108
    * - sp800_56c
      - sphincsplus_common
-     - sphincsplus_sha2
-     - sphincsplus_shake
+     - sphincsplus_sha2_base
+     - sphincsplus_shake_base
    * - stateful_rng
      - stream
      - system_rng
@@ -212,6 +215,10 @@ reviewed:
      - tls13
      - tls13_pqc
      - tls_cbc
+   * - tpm2
+     - tpm2_crypto_backend
+     - tpm2_ecc
+     - tpm2_rsa
    * - tree_hash
      - trunc_hash
      - utils
@@ -223,7 +230,14 @@ reviewed:
 
 Here are some notable module changes compared to the last review (Botan |botan_git_base_ref|):
 
-.. todo:: Update this section for each new version of the document.
+ * Standardized post-quantum algorithms
+
+   * ML-KEM (``ml_kem``) replacing Kyber
+   * ML-DSA (``ml_dsa``) replacing Dilithium
+   * SLH-DSA (``slh_dsa_sha2``, ``slh_dsa_shake``) replacing SPHINCS+
+
+ * TPM 2.0 Wrapper (``tpm2``, ``tpm2_crypto_backend``, ``tpm2_ecc``, ``tpm2_rsa``)
+ * Wrapper for jitterentropy-library (``jitter_rng``)
 
 Patch Description Content
 -------------------------

docs/audit_report/src/01_generic_changes.rst

@@ -4,5 +4,44 @@ Changes Overview
 Since the previously audited version (|botan_git_base_ref|), Botan
 |botan_version| brings some extensions and fixes. The most relevant changes are outlined below.
 
-.. todo:: Outline the most notable changes that came with Botan 3.3.0
-          Presumably, that will be FrodoKEM and LMS or both.
+Introduction of Standardized Post-Quantum Algorithms
+----------------------------------------------------
+
+Additionally to the existing implementations of the round 3 candidates Kyber,
+Dilithium and SPHINCS+, Botan |botan_version| introduces implementations for the
+standards FIPS 203, 204 and 205.
+
+   * ML-KEM (FIPS 203)
+   * ML-DSA (FIPS 204)
+   * SLH-DSA (FIPS 205)
+
+Note that the signature algorithms lack support for pre-hash mode and the
+application-defined context string. Those features were introduced with the
+final standards and can't be implemented without an API extension that was
+postponed to the next minor release of the library.
+
+Jitterentropy RNG Wrapper
+-------------------------
+
+This is a small wrapper around the jitterentropy-library. This library provides
+a high-quality entropy source based on jitter measured in CPU execution times.
+It comes with extensive documentation and estimates on the entropy's quality.
+
+TPM 2.0 Wrapper
+---------------
+
+The TPM 2.0 wrapper provides a high-level interface to TPM-hosted asymmetric key
+material as well as an adapter to the TPM's random number generator.
+Additionally, Botan implements the crypto callbacks introduced with TPM2-TSS
+4.0, which allow to communicate with the TPM without a dependency on a
+third-party crypto library such as OpenSSL or mbedTLS.
+
+New (internal) Elliptic Curve Math Library
+------------------------------------------
+
+Botan |botan_git_base_ref| already introduced a new elliptic curve math library,
+which is now (starting with Botan |botan_version|) used for all elliptic curve
+algorithms, such as ECDH and ECDSA. Apart from a major performance gain,
+applications should not notice this change. The new library uses fixed-length
+data types (instead of the previously used ``BigInt``) and is designed to better
+leverage compiler optimizations.

docs/audit_report/src/02_security_issues.rst

@@ -3,5 +3,3 @@ Security and Vulnerabilities
 
 Currently, we are not aware of any security issues that needed to be addressed
 between |botan_git_base_ref| and |botan_version|.
-
-.. todo:: Update this section with any security issues fixed recently.

docs/audit_report/src/05_summary.rst

@@ -7,7 +7,9 @@ the results of several analysis tools.
 
 The most significant changes are the following:
 
-.. todo:: Add a bullet-point list for the most significant changes in Botan 3.3.0
+* Implementations for the post-quantum standards FIPS 203, 204, and 205
+* A basic TPM 2.0 wrapper
+* A new elliptic curve math library with much better performance
 
 According to the observations of this audit, Botan version |botan_version| keeps the security level of
 the previously reviewed version and complements the old version with various sensible and

docs/audit_report/src/06_bibliography.rst

@@ -35,3 +35,5 @@
 .. [DATA] https://www.usenix.org/conference/usenixsecurity18/presentation/weiser
 
 .. [DATA_GIT] https://github.com/Fraunhofer-AISEC/DATA
+
+.. [DILITHIUM_REFERENCE_IMPLEMENTATION] https://github.com/pq-crystals/dilithium/blob/cbcd8753a43402885c90343cd6335fb54712cda1/ref/poly.c#L277-L279

docs/audit_report/src/side_channels/01_00_results.rst

@@ -38,3 +38,7 @@ Leaks found are described in separate sections.
 The descriptions usually also include the associated source code and, if applicable, the call hierarchy.
 
 .. toctree::
+
+   01_02_ml_dsa
+   01_03_ml_kem
+   01_04_slh_dsa