Merge branch 'master' into pqc/classic_mceliece

.github/actions/setup-build-agent/action.yml

@@ -35,12 +35,13 @@ runs:
       run: print("::warning ::No compiler cache available, build times might suffer")
       shell: python
       if: env.COMPILER_CACHE_LOCATION == '' && inputs.cache-key != ''
-    - uses: actions/cache@v3
+    - uses: actions/cache@v4
       if: env.COMPILER_CACHE_LOCATION != '' && inputs.cache-key != ''
       with:
           path: ${{ env.COMPILER_CACHE_LOCATION }}
           key: ${{ inputs.cache-key }}-${{ github.run_id }}
           restore-keys: ${{ inputs.cache-key }}
+          save-always: true
 
     - name: Setup Visual Studio Environment
       uses: egor-tensin/vs-shell@v2

.github/workflows/ci.yml

@@ -46,7 +46,7 @@ jobs:
     runs-on: ${{ matrix.host_os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -77,7 +77,7 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -103,7 +103,7 @@ jobs:
     runs-on: macos-13
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -118,7 +118,7 @@ jobs:
     name: "Clang Tidy"
     runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -177,12 +177,12 @@ jobs:
       COVERALLS_REPO_TOKEN: pbLoTMBxC1DFvbws9WfrzVOvfEdEZTcCS
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           path: ./source
 
       - name: Fetch BoringSSL fork for BoGo tests
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
         with:
           repository: randombit/boringssl
           ref: rene/runner-20230705
@@ -221,7 +221,7 @@ jobs:
     runs-on: ${{ matrix.host_os }}
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           path: ./source
 
@@ -274,15 +274,15 @@ jobs:
             host_os: macos-13
           - target: emscripten
             compiler: emcc
-            host_os: macos-13
+            host_os: macos-14
 
     runs-on: ${{ matrix.host_os }}
 
     env:
       ANDROID_NDK: android-ndk-r26
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent

.github/workflows/cifuzz.yml

@@ -22,7 +22,7 @@ jobs:
         fuzz-seconds: 180
         dry-run: false
     - name: Upload Crash
-      uses: actions/upload-artifact@v1
+      uses: actions/upload-artifact@v4
       if: failure() && steps.build.outcome == 'success'
       with:
         name: artifacts

.github/workflows/codeql.yml

@@ -24,7 +24,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -56,7 +56,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Initialize CodeQL
         uses: github/codeql-action/init@v2

.github/workflows/nightly.yml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -51,7 +51,7 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -68,7 +68,7 @@ jobs:
     runs-on: ubuntu-22.04
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -86,7 +86,7 @@ jobs:
 
     steps:
       - name: Fetch Botan Repository
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Setup Build Agent
         uses: ./.github/actions/setup-build-agent
@@ -101,7 +101,7 @@ jobs:
           --test-target server
           --parallel $(nproc)
 
-      - uses: actions/upload-artifact@v3
+      - uses: actions/upload-artifact@v4
         with:
           name: tls-anvil-server-test-results
           path: |

doc/api_ref/contents.rst

@@ -31,6 +31,7 @@ API Reference
    tss
    ecc
    compression
+   providers
    pkcs11
    tpm
    otp

doc/api_ref/providers.rst

@@ -0,0 +1,169 @@
+External Providers
+==============================
+
+Botan ships with a variety of cryptographic algorithms in both pure software
+as well as with support from :doc:`hardware acceleration <../hardware_acceleration>`.
+
+Additionally, Botan allows to use external implementations to provide algorithms ("providers").
+
+Integrated Providers
+------------------------------
+
+PKCS#11
+^^^^^^^^^^^^^
+
+PKCS#11 is a standard API for accessing cryptographic hardware. Botan
+ships a :doc:`PKCS#11 provider <pkcs11>` for interacting with PKCS#11
+devices which provide cryptographic algorithms. It is enabled by default.
+
+TPM 1.2
+^^^^^^^^^^^^^
+
+The TPM 1.2 standard is a specification for a hardware device which provides
+cryptographic algorithms. Botan ships a :doc:`TPM provider <tpm>` for interacting
+with TPM devices. It is disabled by default.
+
+CommonCrypto
+^^^^^^^^^^^^^
+
+CommonCrypto is a library provided by Apple for accessing cryptographic
+algorithms. Botan ships a *CommonCrypto* provider for interacting with CommonCrypto.
+It is disabled by default.
+
+The CommonCrypto provider supports the following algorithms:
+
+* SHA-1, SHA-256, SHA-384, SHA-512
+* AES-128, AES-192, AES-256, DES, TDES, Blowfish, CAST-128
+* CBC, CTR, OFB
+
+Provider Interfaces
+------------------------------
+
+Symmetric Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following interfaces can be used to implement providers
+for symmetric algorithms:
+
+* ``AEAD_Mode``
+* ``BlockCipher``
+* ``Cipher_Mode``
+* ``Hash``
+* ``KDF``
+* ``MAC``
+* ``PasswordHashFamily``
+* ``PBKDF``
+* ``StreamCipher``
+* ``XOF``
+
+Each of the interfaces provide a factory method which takes string arguments
+and returns an object implementing the interface. The strings are the name of
+the algorithm to be instantiated and the provider to be used.
+For example, the following code creates a SHA-256 hash object using the
+*CommonCrypto* provider:
+
+.. code-block:: cpp
+
+    #include <botan/hash.h>
+
+    auto hash = Botan::HashFunction::create_or_throw("SHA-256", "CommonCrypto");
+
+    hash->update("Hello");
+    hash->update(" ");
+    hash->update("World");
+    auto digest = hash->final();
+
+    // query the provider currently used
+    std::string provider = hash->provider(); // "CommonCrypto"
+
+Omitting the provider string or leaving it empty means the default provider
+is used. The default provider is the first provider which supports the
+requested algorithm. Depending on how Botan was configured at build time,
+the default provider may be a pure software implementation, a hardware
+accelerated implementation or an implementation using an integrated provider,
+e.g., CommonCrypto.
+
+The following rules apply:
+
+1. If Botan was built with an integrated provider that is hooked into the
+   ``T::create()``/``T::create_or_throw()`` factory methods (currently only *CommonCrypto* is),
+   the default provider is the integrated provider.
+
+2. If Botan was not built with an integrated provider as in (1), but
+   with hardware acceleration support, e.g., AES-NI, and the hardware acceleration
+   is available at runtime, the default provider is the hardware accelerated provider.
+
+3. If Botan was not built with an integrated provider as in (1) and not built
+   with hardware acceleration support, the default provider is the pure software
+   implementation.
+
+Regardless of the default provider, a specific provider can always be requested
+by passing the provider name as the second argument to ``T::create()``/``T::create_or_throw()``.
+Specifically, the special provider name ``"base"`` can always be used to
+request the hardware accelerated (preferred, if available at runtime)
+or pure software implementation (last fallback).
+
+Public Key Algorithms
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The following interfaces support using providers for
+:doc:`public key algorithms <pubkey>`. The interfaces are used
+in a similar way as the interfaces for symmetric algorithms
+described above.
+
+* ``PK_Signer``
+* ``PK_Verifier``
+* ``PK_Key_Agreement``
+* ``PK_Encryptor_EME``
+* ``PK_Decryptor_EME``
+* ``PK_KEM_Encryptor``
+* ``PK_KEM_Decryptor``
+
+Each of the interfaces provides a constructor which takes a key object,
+optional parameters, and a string specifying the provider to be used.
+For example, the following code signs a message using an RSA key with the
+*CommonCrypto* provider:
+
+.. note:: No integrated provider currently supports using any public key algorithm
+    in the way described above, so the example is purely for illustrative purposes.
+
+.. code:: cpp
+
+    #include <botan/auto_rng.h>
+    #include <botan/pk_algs.h>
+    #include <botan/pubkey.h>
+
+    Botan::AutoSeeded_RNG rng;
+    auto key = Botan::create_private_key("RSA", rng, "3072");
+
+    Botan::PK_Signer signer(key, rng, "EMSA3(SHA-256)", Botan::Signature_Format::Standard, "CommonCrypto");
+
+    signer.update("Hello");
+    signer.update(" ");
+    signer.update("World");
+    auto signature = signer.signature(rng);
+
+To create a key object, use ``Botan::create_private_key()``, which takes
+a string specifying the algorithm and the provider to be used. For example, to
+create a 3072 bit RSA key with the *CommonCrypto* provider:
+
+.. note:: No integrated provider currently supports creating any private key
+    in the way described above, so the example is purely for illustrative purposes.
+
+.. code:: cpp
+
+    #include <botan/auto_rng.h>
+    #include <botan/pk_algs.h>
+
+    Botan::AutoSeeded_RNG rng;
+
+    auto key = Botan::create_private_key("RSA", rng, "3072", "CommonCrypto");
+
+Another way to implement a provider for public key algorithms is to implement
+the ``Private_Key`` and ``Public_Key`` interfaces. This allows for different
+use cases, e.g., to use a key stored in a hardware security module, handled
+by a different operating system process (to avoid leaking the key material),
+or even implement an algorithm not supported by Botan. The resulting key class
+can be stored outside Botan and still be used with the ``PK_Signer``,
+``PK_Verifier``, ``PK_Key_Agreement``, ``PK_Encryptor_EME``, ``PK_Decryptor_EME``,
+``PK_KEM_Encryptor``, and ``PK_KEM_Decryptor`` interfaces.

doc/api_ref/tls.rst

@@ -1317,14 +1317,28 @@ The asio Stream offers the following interface:
 
 .. _https_client_example:
 
-Code Example: HTTPS Client
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Code Examples: HTTPS Client using Boost Beast
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The code below illustrates how to build a simple HTTPS client based on the TLS Stream and Boost.Beast. When run, it fetches the content of `https://botan.randombit.net/news.html` and prints it to stdout.
+Starting with Botan 3.3.0 (and assuming a recent version of Boost), one may use
+Botan's TLS using C++20 coroutines. The following example implements a simple
+HTTPS client that may be used to fetch content from web servers:
+
+.. literalinclude:: /../src/examples/tls_stream_coroutine_client.cpp
+   :language: cpp
+
+Of course, the ASIO stream may also be used in a more traditional way, using
+callback handler methods instead of coroutines:
 
 .. literalinclude:: /../src/examples/tls_stream_client.cpp
    :language: cpp
 
+For some websites this might not work and report a "bad_certificate". Botan's
+default TLS policy requires that the server sends a valid CRL or OCSP response.
+Some servers don't do that and thus the certificate is rejected. To disable this
+check, derive the default policy and override `require_cert_revocation_info()`
+accordingly.
+
 .. _tls_session_encryption:
 
 TLS Session Encryption

doc/credits.rst

@@ -163,7 +163,7 @@ snail-mail address (S), and Bitcoin address (B).
   N: René Meusel
   E: [email protected]
   W: https://www.rohde-schwarz.com/cybersecurity
-  D: CI, TLS 1.3, Kyber, Dilithium, SPHINCS+
+  D: CI, TLS 1.3, Kyber, Dilithium, SPHINCS+, FrodoKEM
   S: Berlin, Germany
 
   N: Philippe Lieser

doc/migration_guide.rst

@@ -26,6 +26,14 @@ algorithm headers (such as ``aes.h``) have been removed. Instead you should
 create objects via the factory methods (in the case of AES,
 ``BlockCipher::create``) which works in both 2.x and 3.0
 
+Errata: ``pk_ops.h``
+^^^^^^^^^^^^^^^^^^^^
+
+Between Botan 3.0 and 3.2 the public header ``pk_ops.h`` was removed
+accidentally. This header is typically required for specialized applications
+that interface with dedicated crypto hardware. If you are migrating such an
+application, please make sure to use Botan 3.3 or newer.
+
 Build Artifacts
 ---------------