Revision control
Copy as Markdown
Other Tools
= Backends policy
== What a backend is
A *backend* is a crypto library that librnp's OpenSSL-family backend
code is configured against at build time via
`-DCRYPTO_BACKEND=<name>`. The backend provides public-key algorithms,
symmetric ciphers, hash functions, and RNG that librnp uses
internally.
== Current backends
[cols="1,1,1,2", options="header"]
|===
| Backend | Tier | Dep source | Notes
| `botan` | 1 | source tarball (Linux/macOS), vcpkg (Windows) | Default. Supports PQC via Botan 3 PQ modules.
| `openssl` | 1 | source tarball (Linux/macOS), vcpkg (Windows) | PQC gated off (`openssl_nope(ENABLE_PQC, ...)`).
|===
== Backend requirements
A backend must:
* Ship a static-library form (`.a` or `.lib`).
* Expose the algorithms rnp's CMake feature-detection probes for
(see `src/lib/CMakeLists.txt` `_openssl_required_features`).
* Support the public OpenSSL 1.1 API (no internal APIs like
`EVP_PKEY_meth_*` — see issue #2440).
* Build with `-fPIC` so the static archive can be linked into a
shared library downstream.
* Pass `ci/test_prebuilt.sh` end-to-end (compile, link, run
`rnp_ffi_create()`).
== Backend config file
Each backend has a config file at `ci/backends/<name>.env` declaring:
* `BACKEND_DESCRIPTION` — human-readable name.
* `BACKEND_DEPS` — extra deps to install (beyond common bzip2+zlib).
* `BACKEND_CMAKE_FLAGS` — CMake flags for the rnp configure step.
* `BACKEND_HEADERS_DIR` — subdirectory under `include/` for backend headers.
* `BACKEND_LINK_LIBS` — Unix link flags (space-separated).
* `BACKEND_WINDOWS_LINK_LIBS` — MSVC link flags (space-separated).
* `BACKEND_LIB_NAMES` — required static archives (comma-separated).
* `BACKEND_WINDOWS_LIB_NAMES` — same for Windows (`.lib` extension).
The build scripts, the test, and the MANIFEST.txt generator all read
from this file. Single source of truth per backend.
== Adding a backend
1. Create `ci/backends/<name>.env` with all required fields.
2. Add `backend: [<name>]` to the matrix in `prebuilt.yml` if the
backend should ship prebuilt.
3. Ensure the backend's build function exists in
`ci/build_prebuilt.sh` (e.g. `build_<name>()`) or is handled by
vcpkg on Windows.
4. Run `ci/test_prebuilt.sh` against a locally-built tarball.
5. Open a PR; a maintainer reviews and assigns a tier.
== Deprecating a backend
1. Announce in `CHANGELOG.md`.
2. Remove from the matrix in `prebuilt.yml`.
3. Delete `ci/backends/<name>.env`.
4. Clean up any backend-specific build functions.