Botan 3.2.0: Prepare Documents for Submission

.github/workflows/ci.yml

@@ -56,6 +56,7 @@ jobs:
       matrix:
         element:
           - {name: Crypto Documentation, dir: docs/cryptodoc}
+          - {name: Audit Method Description, dir: docs/audit_method}
           - {name: Test Specification, dir: docs/testspec}
           - {name: Architecture, dir: docs/architecture}
 

config/botan.env

@@ -14,7 +14,7 @@ BOTAN_VERSION=3.2.0
 # 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=6f466a2704a31856ebc27451ca861527d3dd00a1
+BOTAN_REF=3.2.0
 
 # 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_method/pyproject.toml

@@ -10,6 +10,7 @@ Sphinx = "^6.1.3"
 pylatexenc = "^2.10"
 
 auditinfo = { path = "../../tools/auditinfo", develop = true }
+sourceref = { path = "../../tools/sourceref", develop = true }
 
 [tool.poetry.dev-dependencies]
 esbonio = "^0.16.1"

docs/audit_method/src/00_00_preface.rst

@@ -23,6 +23,8 @@ Botan-Versionen zum Einsatz kommt.
 | Daniel Neus (DN)
 | Philippe Lieser (PL)
 | René Meusel (RM)
+| Andreas Seelos-Zankl (ASZ), Fraunhofer AISEC
+| Alexander Wagner (AW), Fraunhofer AISEC
 
 **Dokumentrevision**
 

docs/audit_method/src/00_01_changelog.rst

@@ -38,3 +38,6 @@
    |         |         | - Beschreibung der neuen Audit-Methode basierend auf GitHub  |            |
    |         |         |   Patches                                                    |            |
    +---------+---------+--------------------------------------------------------------+------------+
+   | 3.2.0   | RM, AW, | - Detailbeschreibung: Seitenkanalanalyse mit DATA            | 10.10.2023 |
+   |         | ASZ     |                                                              |            |
+   +---------+---------+--------------------------------------------------------------+------------+

docs/audit_method/src/90_references.rst

@@ -48,3 +48,15 @@
 
 .. [DATA]
    `https://github.com/Fraunhofer-AISEC/DATA <https://github.com/Fraunhofer-AISEC/DATA>`_
+
+.. [INTEL_PIN] https://www.intel.com/content/www/us/en/developer/articles/tool/pin-a-dynamic-binary-instrumentation-tool.html
+
+.. [TVLA] https://csrc.nist.gov/CSRC/media/Events/Non-Invasive-Attack-Testing-Workshop/documents/08_Goodwill.pdf
+
+.. [RDC] https://proceedings.neurips.cc/paper/2013/file/aab3238922bcc25a6f606eb525ffdc56-Paper.pdf
+
+.. [DATA_GIT] https://github.com/Fraunhofer-AISEC/DATA
+
+.. [CT_GRIND] https://github.com/agl/ctgrind
+
+.. [VALGRIND_MEMCHECK] https://valgrind.org/docs/manual/mc-manual.html

docs/audit_method/src/conf.py

@@ -36,6 +36,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+  'sourceref'
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/audit_report/scripts/audited_modules_list.py

@@ -0,0 +1,119 @@
+import sys
+import argparse
+import os
+import re
+
+import auditutils
+
+# Runs Botan's `./configure.py --module-policy=bsi` with the module
+# configuration that needs auditing and collects all its dependencies
+# in an rST table.
+
+def platform_dependent_modules():
+    """ Modules whose parents are part of the audit scope but that are platform
+        dependent or dependent on external libraries and therefore might not
+        show up in a particular run of ./configure.py.
+
+        NOTE: Dependency resolution _will not happen_ for those modules!
+    """
+    return set([
+        'aes_armv8',
+        'aes_ni',
+        'aes_power8',
+        'aes_vperm',
+        'argon2_avx2',
+        'argon2_ssse3',
+        'certstor_sql',
+        'certstor_sqlite3',
+        'certstor_system_macos',
+        'certstor_system_windows',
+        'ghash_cpu',
+        'ghash_vperm',
+        'keccak_perm_bmi2',
+        'sha1_armv8',
+        'sha1_sse2',
+        'sha1_x86',
+        'sha2_32_armv8',
+        'sha2_32_bmi2',
+        'sha2_32_x86',
+        'sha2_64_bmi2',
+    ])
+
+def additional_modules():
+    """ Modules that are not in Botan's BSI module policy but that are
+        part of the audit scope regardless.
+
+        NOTE: Dependency resolution will be performed for the listed modules.
+    """
+    return set([
+        'certstor_flatfile',
+        'certstor_system',
+        'dilithium_aes',
+        'dilithium',
+        'ffi',
+        'kyber_90s',
+        'kyber',
+        'pkcs11',
+        'shake',
+        'sphincsplus_sha2',
+        'sphincsplus_shake',
+        'tls_cbc',
+        'tls12',
+        'tls13_pqc',
+        'tls13',
+        'xts',
+    ])
+
+
+def print_table(columns: int, modules: list[str]):
+    print(".. list-table::")
+    print()
+
+    for i, module in enumerate(modules):
+        row_sep = "*" if i % columns == 0 else " "
+        print(f"   {row_sep} - {module}")
+
+    if len(modules) % columns != 0:
+        for _ in range(columns - (len(modules) % columns)):
+            print("     -")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Generate an rST table of the audited modules in Botan.')
+    parser.add_argument('-r', '--repo-location',
+                        help='Path to a local checkout of the Botan repository (overrides config.yml and defaults to AUDIT_REPO_LOCATION).',
+                        default=os.environ.get('AUDIT_REPO_LOCATION'))
+    parser.add_argument('-c', '--columns',
+                        help='Number of columns in the final rST table',
+                        default=4)
+
+    args = parser.parse_args(sys.argv[1:])
+    conf_py = os.path.join(args.repo_location, "configure.py")
+
+    # verify that the manually listed modules are consistent with
+    # the modules offered by the targetted Botan version
+    available_modules = set(auditutils.run([conf_py, "--list-modules"], working_directory=args.repo_location).decode("utf-8").splitlines())
+    unknown_platform_modules = platform_dependent_modules() - available_modules
+    unknown_additional_modules = additional_modules() - available_modules
+    if unknown_platform_modules:
+        raise RuntimeError("Unknown platform dependent modules: %s" % ', '.join(unknown_platform_modules))
+    if unknown_additional_modules:
+        raise RuntimeError("Unknown additional modules: %s" % ', '.join(unknown_additional_modules))
+
+    # list all modules that are part of the audit scope
+    out = auditutils.run([conf_py,
+                          "--module-policy=bsi",
+                          "--enable-modules=%s" % ','.join(additional_modules())],
+                         working_directory=args.repo_location).decode("utf-8")
+    match = re.search(r'Loading modules: (.*)$', out, re.MULTILINE)
+    if not match:
+        raise RuntimeError("Didn't find loaded modules in configure.py output")
+    modules = list(set(match.group(1).split(' ')) | platform_dependent_modules())
+    modules.sort()
+
+    # print the final result
+    print_table(args.columns, modules)
+
+if __name__ == "__main__":
+    sys.exit(main())