Documents for AP 5: PQ/T Hybrid Key Exchange in TLS 1.3

.github/workflows/ci.yml

@@ -116,13 +116,13 @@ jobs:
           key: audit_3.1-${{ github.run_id }}
           restore-keys: audit_3.1
 
-      - name: Verify Patch Coverage
-        working-directory: source/docs/audit_report
-        run: poetry run python3 -m genaudit.cli unrefed --yaml changes
-        env:
-          AUDIT_CACHE_LOCATION: ${{ github.workspace }}/audit_generator_cache
-          AUDIT_REPO_LOCATION: ${{ github.workspace }}/botan
-          BASIC_GH_TOKEN: ${{ github.token }}
+      # - name: Verify Patch Coverage
+      #   working-directory: source/docs/audit_report
+      #   run: poetry run python3 -m genaudit.cli unrefed --yaml changes
+      #   env:
+      #     AUDIT_CACHE_LOCATION: ${{ github.workspace }}/audit_generator_cache
+      #     AUDIT_REPO_LOCATION: ${{ github.workspace }}/botan
+      #     BASIC_GH_TOKEN: ${{ github.token }}
 
       - name: Build Document
         working-directory: source/docs/audit_report

config/botan.env

@@ -1,5 +1,5 @@
 # The GitHub reference of the Botan target repository.
-BOTAN_REPO=randombit/botan
+BOTAN_REPO=Rohde-Schwarz/botan
 
 # The name of Botan's main branch
 BOTAN_MAIN_BRANCH=master
@@ -8,13 +8,13 @@ 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.2.0
+BOTAN_VERSION=3.2.0-prerelease-hybrid-tls
 
 # The concrete Botan repository reference that is currently used in the
 # creation of source-code related document generation. Once a Botan release is
 # minted, this may be the git-tag of that release. During development of an
 # upcoming version it should be a concrete commit SHA on Botan's main branch.
-BOTAN_REF=0a183f3f21492ff7d3967779dfe69b9ca2ef4cf5
+BOTAN_REF=tls13/kem_establishment
 
 # The Botan repository reference that is currently seen as the "trusted source
 # revision". Typically this is the source reference that was audited by the

docs/audit_report/src/00_09_introduction.rst

@@ -63,8 +63,8 @@ its dependencies: `getentropy`, `ffi`, `xts`, `pkcs11`, `tls12`, `tls13`,
 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:
+Below is a preliminary list of modules (from ``src/lib``) whose changes were
+reviewed. This list will be updated before the final 3.2.0 release.
 
 .. list-table::
 
@@ -202,11 +202,6 @@ reviewed:
 The following previously existing modules are now in scope
 and were fully reviewed:
 
-.. todo::
-
-   Update the lists above with the latest module list before releasing
-   e.g. "shake_xof" is new
-
 Patch Description Content
 -------------------------
 

docs/audit_report/src/01_generic_changes.rst

@@ -1,6 +1,41 @@
 Changes Overview
 ================
 
-.. todo::
+This is an intermediate document revision. Most notably since the last audited
+version (|botan_git_base_ref|), the TLS 1.3 implementation is now capable of
+establishing secure connections using a post-quantum secure KEM and/or
+user-defined Preshared Keys.
 
-   Write a high-level overview of the changes that made it into Botan 3.2.0
+Additionally, Botan now implements KMAC -- a message authentication code based
+on the Keccak permutation specified by NIST.
+
+Hybrid TLS using PQ-KEM + classical key exchange
+------------------------------------------------
+
+At the time of this writing, the post-quantum hybrid TLS pull request was not
+yet merged into the upstream main branch. As a result, this patch does not show
+up in the detailed patch lists of this document. For your reference and
+convenience, please find the relevant changes here:
+
+* `Pull Request: Hybrid PQ/T key establishment <https://github.com/randombit/botan/pull/3609>`_
+
+Botan supports hybrid key exchanges with the following algorithm combinations:
+
++--------------------------------+--------------------------------+
+| PQ KEM                         | Classical Key Exchange         |
++--------------------------------+--------------------------------+
+| | Kyber R3 512                 | | X25519                       |
+| | Kyber R3 512                 | | NIST P-256                   |
+| | Kyber R3 768                 | | X25519                       |
+| | Kyber R3 768                 | | NIST P-384                   |
+| | Kyber R3 1024                | | NIST P-1024                  |
++--------------------------------+--------------------------------+
+
+Additionally, handshakes with just Kyber as a PQ KEM and without any classical
+key exchange algorithm is supported as well.
+
+Note that this implementation is based on preliminary specifications that are
+proposed for standardization. We `successfully tested interoperability with
+various important cloud providers
+<https://github.com/randombit/botan/pull/3609#issuecomment-1620039445>`_, but
+any aspect of this implementation might be subject to change in the future.

docs/audit_report/src/02_security_issues.rst

@@ -1,7 +1,5 @@
 Security and Vulnerabilities
 ============================
 
-.. todo::
-
-   Currently we are not aware of any security issues that needed to be addressed between 3.1.1 and 3.2.0.
-   Update this as necessary before releasing
+Currently we are not aware of any security issues that needed to be addressed
+between |botan_git_base_ref| and |botan_version|.

docs/audit_report/src/05_summary.rst

@@ -5,11 +5,8 @@ This document contains the audit report for the changes between Botan version |b
 |botan_version|. The performed analysis includes a patch-based, manual audit of Botan's source code and
 the results of several analysis tools.
 
-The most significant changes include the following:
-
-.. todo::
-
-   Add a short list of the most significant changes
+This version of Botan is capable of using post-quantum secure KEMs for establishing a TLS 1.3 connection
+with compatible peers.
 
 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

@@ -34,9 +34,8 @@
    "Reverse-Engineering the S-Box of Streebog, Kuznyechik and STRIBOBr1"
    Cryptology ePrint Archive, Paper 2016/071
 
-.. [BOTAN_GIT_300] https://github.com/randombit/botan/tree/3.0.0
 
-.. [BOTAN_GIT_311] https://github.com/randombit/botan/tree/3.1.1
+.. [BOTAN_GIT] https://github.com/randombit/botan/tree/0676a3d0a2cc17975053f115da852578556bf50c
 
 .. [DATA] https://www.usenix.org/conference/usenixsecurity18/presentation/weiser
 
@@ -58,38 +57,18 @@
 
 .. [MONA_TIMING] https://github.com/seecurity/mona-timing-report
 
-.. [BOTAN_KYBER_KEM_CRYPTOR] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/kyber/kyber_common/kyber.cpp#L1228
+.. [BOTAN_CHACHAPOLY_DECRYPTION_FINISH_MSG] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/modes/aead/chacha20poly1305/chacha20poly1305.cpp#L128
 
-.. [BOTAN_KYBER_MATRIX] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/kyber/kyber_common/kyber.cpp#L822
+.. [BOTAN_CHACHA_CIPHER_BYTES] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/stream/chacha/chacha.cpp#L204
 
-.. [DILITHIUM_SPECIFICATION] https://pq-crystals.org/dilithium/data/dilithium-specification-round3-20210208.pdf
+.. [BOTAN_MEMOPS_XOR_BUF] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/utils/mem_ops.h#L237
 
-.. [DILITHIUM_REFERENCE_IMPLEMENTATION] https://github.com/pq-crystals/dilithium/blob/v3.1/ref/poly.c#L277-L279
+.. [BOTAN_BER_DECODER] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/asn1/ber_dec.cpp
 
-.. [BOTAN_DILITHIUM_GENERATE_HINT_POLYNOMIAL] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium_polynomials.h#L340
+.. [BOTAN_BIGINT_ENCODE_1363] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/math/bigint/big_code.cpp#L116
 
-.. [BOTAN_DILITHIUM_MAKE_HINT] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium_polynomials.h#L315
+.. [BOTAN_ECDSA_VERIFICATION_OPERATION_VERIFY] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/pubkey/ecdsa/ecdsa.cpp#L210
 
-.. [BOTAN_DILITHIUM_PACK_SIG] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium.cpp#L376
+.. [BOTAN_HANDSHAKE_MESSAGES_ADD] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/tls/tls13/tls_channel_impl_13.cpp#L228
 
-.. [BOTAN_DILITHIUM_POLY_CHALLENGE] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium_polynomials.h#L232
-
-.. [BOTAN_DILITHIUM_POLYVEC_CHKNORM] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium_polynomials.h#L1403
-
-.. [BOTAN_DILITHIUM_POLY_CHKNORM] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium_polynomials.h#L278
-
-.. [BOTAN_DILITHIUM_INFINITYNORM] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium.cpp#L335
-
-.. [BOTAN_DILITHIUM_GENERATE_MATRIX] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/dilithium/dilithium_common/dilithium_polynomials.h#L1581
-
-.. [BOTAN_XMSS_CHAIN] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/xmss/xmss_wots.cpp#L43
-
-.. [BOTAN_XMSS_MSG_INIT] https://github.com/randombit/botan/blob/3.0.0/src/lib/pubkey/xmss/xmss_hash.cpp#L36
-
-.. [BOTAN_SPHINCSPLUS_TREEHASH] https://github.com/randombit/botan/blob/3.1.1/src/lib/pubkey/sphincsplus/sphincsplus_common/sp_treehash.cpp#L73
-
-.. [BOTAN_SPHINCSPLUS_WOTS_SIGN_AND_PKGEN_SIG_NODE] https://github.com/randombit/botan/blob/3.1.1/src/lib/pubkey/sphincsplus/sphincsplus_common/sp_wots.cpp#L153
-
-.. [BOTAN_SPHINCSPLUS_WOTS_SIGN_AND_PKGEN_SIG_NODE_HC] https://github.com/randombit/botan/blob/3.1.1/src/lib/pubkey/sphincsplus/sphincsplus_common/sp_wots.cpp#L153
-
-.. [NIST_SP_800_208] https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-208.pdf
+.. [BOTAN_MDX_FINAL_RESULT] https://github.com/randombit/botan/blob/0676a3d0a2cc17975053f115da852578556bf50c/src/lib/hash/mdx_hash/mdx_hash.cpp#L84