Vendored Crypto Library Sources
================================

Each cryptographic library is included as a git submodule so every build uses
an exact, auditable commit.  Only the maintainer should bump a submodule version
and only after reviewing the upstream changelog and CVE advisories.

How to initialise after cloning
---------------------------------

.. code-block:: shell

    git submodule update --init --recursive

How to upgrade a submodule to a new release
---------------------------------------------

1. Check the upstream release notes and any associated CVEs.
2. Run::

        cd vendors/<library>
        git fetch --tags
        git checkout <new-tag>
        cd ../..
        git add vendors/<library>
        git commit -m "chore(vendors): bump <library> to <new-tag>"

3. Update the pin record in this file (below) and re-run the full test suite::

        cargo test --workspace

4. Update ``docs/ccc_rust_plan_phases.rst`` to record the new version.

Pinned Submodules
-----------------

+---------+-------------------------------------------+---------------+------------------------------------------+
| Library | Upstream repository                       | Pinned tag    | Rust interface crate                     |
+=========+===========================================+===============+==========================================+
| wolfssl | https://github.com/wolfSSL/wolfssl        | v5.7.2-stable | wolfssl (crates.io)                      |
+---------+-------------------------------------------+---------------+------------------------------------------+

Future submodules (Phase 8)
----------------------------

+-----------+----------------------------------------------+--------------+-----------------------------+
| Library   | Upstream repository                          | Target tag   | Rust interface crate        |
+===========+==============================================+==============+=============================+
| libsodium | https://github.com/jedisct1/libsodium        | 1.0.20       | sodiumoxide / safe_libsodium|
+-----------+----------------------------------------------+--------------+-----------------------------+
| liboqs    | https://github.com/open-quantum-safe/liboqs  | 0.10.x       | oqs (crates.io)             |
+-----------+----------------------------------------------+--------------+-----------------------------+
| boringssl | https://boringssl.googlesource.com/boringssl | TBD          | boring (crates.io)          |
+-----------+----------------------------------------------+--------------+-----------------------------+
| openssl   | https://github.com/openssl/openssl           | 3.x          | openssl (crates.io)         |
+-----------+----------------------------------------------+--------------+-----------------------------+