Backport: Document housekeeping

sehlen-bsi · Jul 18, 2024 · 7563b3c · 7563b3c
1 parent dcb2cc0
commit 7563b3c
Show file tree

Hide file tree

Showing 13 changed files with 68 additions and 36 deletions.
diff --git a/config/botan.env b/config/botan.env
@@ -35,6 +35,15 @@ BOTAN_REF=3.5.0
 # previous project or iteration.
 BOTAN_BASE_REF=3.4.0
 
+# The Copyright year reflected in all documents. Remember to update this every year.
+# (We don't generate the date automatically, to allow future re-builds of documents
+# that still reflect the original copyright year.)
+DOCUMENT_COPYRIGHT_YEAR=2024
+
+# Copyright holder. The individual or organization that claims the copyright of
+# the documents to be generated and released.
+DOCUMENT_COPYRIGHT_HOLDER="Rohde & Schwarz"
+
 # The GitHub reference of the Audit documentation repository.
 AUDITDOC_REPO=sehlen-bsi/botan-docs
 

diff --git a/docs/architecture/src/01_architecture.rst b/docs/architecture/src/01_architecture.rst
@@ -54,7 +54,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.
-For further details, please see the Handbook section 16.1 or the online documentation:
+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>`_
 
 Botan Build System
@@ -72,7 +72,7 @@ E.g. the BSI build policy :srcref:`src/build-data/policy/bsi.txt` can be used to
 
 Further details on the usage and implementation of Botan's build system are available here:
 
- * Handbook sections 4 and 16.2 or
+ * Handbook sections 4 and 18.2 or
  * the online documentation
  * `Building the library <https://botan.randombit.net/handbook/building.html>`_
  * `Understanding configure.py <https://botan.randombit.net/handbook/dev_ref/configure.html>`_
@@ -99,7 +99,7 @@ Similar interfaces exist; e.g. ``HashFunction``, ``MessageAuthenticationCode``,
 
 Other concepts like random number generators, public/private keys, block/stream ciphers or asymmetric operations are also clustered with similar abstract base classes.
 
-Further details can be found in the handbook (section 7), the API reference documentation or online:
+Further details can be found in the handbook (section 8), the API reference documentation or online:
 
  * `API Reference Handbook <https://botan.randombit.net/handbook/api_ref/contents.html>`_
  * `Doxygen Documentation <https://botan.randombit.net/doxygen/>`_
@@ -142,7 +142,7 @@ Unit and Integration Tests
 Botan contains an extensive test suite that aims to cover the library source code with positive and negative tests.
 The test framework is homebrew and provides functionality for both typical "Arrange-Act-Assert"-style unit tests as well as more elaborate integration tests and external test-vector based KAT tests.
 
-Further details are in the handbook section 16.3 or the online documentation:
+Further details are in the handbook section 18.3 or the online documentation:
 `Test Framework <https://botan.randombit.net/handbook/dev_ref/test_framework.html>`_
 
 

diff --git a/docs/architecture/src/conf.py b/docs/architecture/src/conf.py
@@ -22,8 +22,8 @@
 # -- Project information -----------------------------------------------------
 
 project = f'Library Architecture Overview'
-copyright = '2023, Rohde & Schwarz'
-author = 'Rohde & Schwarz'
+copyright = f'{auditinfo.document_copyright_year()}, {auditinfo.document_copyright_holder()}'
+author = f'{auditinfo.document_copyright_holder()}'
 
 # The full version, including alpha/beta/rc tags
 release = auditinfo.botan_version()

diff --git a/docs/audit_method/src/90_references.rst b/docs/audit_method/src/90_references.rst
@@ -6,21 +6,22 @@
 .. [TESTRP]
  Daniel Neus, René Fischer, René Meusel:
  "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan): Test Report",
- Version 1.5.0, 21.11.2022.
+ Release |botan_version|
 
 .. [TESTSP]
  René Fischer, Juraj Somorovsky, Sergii Cherkavskyi, René Meusel, Fabian Albert:
  "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan): Test Specification",
- Version 1.5.1, 01.04.2023.
+ Release |botan_version|
 
 .. [ARCH]
  Rohde & Schwarz Cybersecurity
- "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan): Library Architecture Overview"
+ "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan): Library Architecture Overview",
+ Release |botan_version|
 
 .. [CRYPD]
- René Fischer, Juraj Somorovsky, Tobias Niemann, Fabian Weißberg, Sergii Cherkavskyi, Philippe Lieser, René Meusel:
- "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan): Cryptogrphic Documentation"
- Version 1.5.0, 03.11.2022.
+ René Fischer, Juraj Somorovsky, Tobias Niemann, Fabian Weißberg, Sergii Cherkavskyi, Philippe Lieser, René Meusel, Fabian Albert, Amos Treiber:
+ "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan): Cryptographic Documentation"
+ Release |botan_version|
 
 .. [SHATRD]
  Stevens, M., Bursztein, E., Karpman, P., Albertini, A., Markov, Y. (2017).

diff --git a/docs/audit_method/src/conf.py b/docs/audit_method/src/conf.py
@@ -22,8 +22,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Prüfmethodik für die Freigabe neuer Botan-Versionen'
-# copyright = '???'
-author = 'Rohde & Schwarz'
+copyright = f'{auditinfo.document_copyright_year()}, {auditinfo.document_copyright_holder()}'
+author = f'{auditinfo.document_copyright_holder()}'
 
 # The full version, including alpha/beta/rc tags
 release = auditinfo.botan_version()

diff --git a/docs/audit_report/src/06_bibliography.rst b/docs/audit_report/src/06_bibliography.rst
@@ -6,29 +6,29 @@
 .. [PRM] René Fischer, Juraj Somorvsky, Daniel Neus, Phillippe Lieser, René Meusel:
  "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan):
  Prüfmethodik für die Freigabe neuer Botan-Versionen",
- Release TBD
+ Release |botan_version|
 
 .. [CRYPD] René Fischer, Juraj Somorovsky, Tobias Niemann, Fabian Weißberg,
  Sergii Cherkavskyi, Philippe Lieser, René Meusel, Amos Treiber, Fabian Albert:
  "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan):
  Cryptographic Documentation",
- Release TBD
+ Release |botan_version|
 
 .. [REFG] Jack Lloyd, Daniel Neus, René Fischer, Juraj Somorovsky, Tobias Niemann:
  "Botan Reference Guide",
- Release 3.1.1
+ Release |botan_version|
 
 .. [ARCH] "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan):
- Botan Prüfung 3.1.1 - Library Architecture Overview",
- Release TBD
+ Library Architecture Overview",
+ Release |botan_version|
 
 .. [TESTSP] "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan):
  Test Specification",
- Release TBD
+ Release |botan_version|
 
 .. [TESTRP] "Pflege und Weiterentwicklung der Kryptobibliothek Botan (Weiterentwicklung Botan):
  Botan Test Report",
- Release TBD
+ Release |botan_version|
 
 .. [BOTAN_GIT] https://github.com/randombit/botan/tree/0676a3d0a2cc17975053f115da852578556bf50c
 

diff --git a/docs/audit_report/src/conf.py b/docs/audit_report/src/conf.py
@@ -22,8 +22,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Audit Report'
-# copyright = '???'
-author = 'Rohde & Schwarz'
+copyright = f'{auditinfo.document_copyright_year()}, {auditinfo.document_copyright_holder()}'
+author = f'{auditinfo.document_copyright_holder()}'
 
 # The full version, including alpha/beta/rc tags
 release = auditinfo.botan_version()

diff --git a/docs/cryptodoc/src/90_bibliographie.rst b/docs/cryptodoc/src/90_bibliographie.rst
@@ -232,13 +232,13 @@
  NIST PQC Challenge Round 3 Submission, 2021,
  https://sphincs.org/data/sphincs+-r3.1-specification.pdf
 
-.. [TR-02102-1] BSI Technische Richtlinie BSI TR-02102-1:
- "Kryptographische Verfahren: Empfehlungen und Schlüssellängen",
- Version 2022-01, 28.01.2022
+.. [TR-02102-1] BSI Technical Guideline BSI TR-02102-1:
+ "Cryptographic Mechanisms: Recommendations and Key Lengths",
+ Version 2024-01, 02.02.2024
 
-.. [TR-02102-2] BSI Technische Richtlinie BSI TR-02102-2:
- "Verwendung von Transport Layer Security (TLS)",
- Version 2022-01, 24.01.2022
+.. [TR-02102-2] BSI Technical Guideline BSI TR-02102-2:
+ "Cryptographic Mechanisms: Recommandations and Key Lengths: Use of Transport Layer Security (TLS)",
+ Version 2024-01, 29.02.2024
 
 .. [TR-02103] BSI Technische Richtlinie BSI TR-02103
  "X.509 Zertifikate und Zertifikatspfadvalidierung"

diff --git a/docs/cryptodoc/src/conf.py b/docs/cryptodoc/src/conf.py
@@ -21,8 +21,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Cryptographic Documentation'
-# copyright = '???'
-author = 'Rohde & Schwarz'
+copyright = f'{auditinfo.document_copyright_year()}, {auditinfo.document_copyright_holder()}'
+author = f'{auditinfo.document_copyright_holder()}'
 
 # The full version, including alpha/beta/rc tags
 release = auditinfo.botan_version()

diff --git a/docs/testreport/src/conf.py b/docs/testreport/src/conf.py
@@ -21,8 +21,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Test Report'
-# copyright = '???'
-author = 'Rohde & Schwarz'
+copyright = f'{auditinfo.document_copyright_year()}, {auditinfo.document_copyright_holder()}'
+author = f'{auditinfo.document_copyright_holder()}'
 
 # The full version, including alpha/beta/rc tags
 release = auditinfo.botan_version()

diff --git a/docs/testspec/src/conf.py b/docs/testspec/src/conf.py
@@ -22,8 +22,8 @@
 # -- Project information -----------------------------------------------------
 
 project = 'Test Specification'
-# copyright = '???'
-author = 'Rohde & Schwarz'
+copyright = f'{auditinfo.document_copyright_year()}, {auditinfo.document_copyright_holder()}'
+author = f'{auditinfo.document_copyright_holder()}'
 
 # The full version, including alpha/beta/rc tags
 release = auditinfo.botan_version()

diff --git a/internal/release_checklist.md b/internal/release_checklist.md
@@ -41,6 +41,20 @@ on the document repo's main branch.
  their initials. The datestamp in the changelog should be the day of the final
  content update and reasonably close to the final release date of the document.
 
+* **Double-check References in the Documents**
+
+ * Architecture Overview
+
+ This document contains hard-coded section-specific references into Botan's
+ upstream handbook. Currently we have to manually check and update them for
+ each release.
+
+ * Cryptographic Documentation
+
+ We are referencing BSI's technical guidelines and they are updated regularly.
+ Make sure that the references are up-to-date and that any changes in the
+ guidelines do not affect Botan's conformance.
+
 * **Audit Report Summaries**
 
  * *Update the "audited modules list"*

diff --git a/tools/auditinfo/auditinfo/botan.py b/tools/auditinfo/auditinfo/botan.py
@@ -10,7 +10,7 @@ def auditors_file_path() -> str:
  return os.path.join(repository_root(), "config", "auditors.yml")
 
 def __conf_var_pattern():
- return re.compile(r"(^[a-zA-Z_0-9]+)=(.+)\n$")
+ return re.compile(r"(^[a-zA-Z_0-9]+)=\"?([^\"]+)\"?\n$")
 
 def __get_from_config(env_var: str) -> str:
  cfgpattern = __conf_var_pattern()
@@ -74,6 +74,14 @@ def botan_get_released_source_tarball_signature() -> str:
  """ The URL of the signature of the source tarball of the currently targeted Botan version """
  return __get_from_config("BOTAN_SOURCE_ARCHIVE_TEMPLATE").replace("XXX", botan_version()) + ".asc"
 
+def document_copyright_year() -> int:
+ """ The year of the original document release and copyright notice """
+ return __get_from_config("DOCUMENT_COPYRIGHT_YEAR")
+
+def document_copyright_holder() -> str:
+ """ The year of the original document release and copyright notice """
+ return __get_from_config("DOCUMENT_COPYRIGHT_HOLDER")
+
 def auditdoc_github_handle() -> str:
  """ The repository handle of the audit documentation on GitHub """
  return __get_from_config("AUDITDOC_REPO")