Skip to content

Integration Guide

Jay edited this page Oct 3, 2026 · 1 revision

Integration Guide

Consuming libcertpp from another project. For the full CMake reference see docs/build.md; this page covers the decisions a consumer has to make, and the two things you should know before deploying it anywhere that matters.

Building it

cmake -S . -B build
cmake --build build --config Debug

A shared library by default. The options:

Option Default What it does
CERTPP_BUILD_SHARED ON OFF builds a static library instead
CERTPP_BUILD_TESTS ON the doctest suite, registered with CTest
CERTPP_BUILD_EXAMPLES ON the examples/ programs
CERTPP_RNG_FALLBACK OFF lets crypto::CRng fall back to std::random_device if the OS CSPRNG is unavailable
CERTPP_DISABLE_HWACCEL_SIMD OFF forces the portable path instead of PCLMULQDQ / ADX+BMI2 / SSE2
CERTPP_DISABLE_HWACCEL_SHA OFF forces the portable path instead of SHA-NI
CERTPP_DISABLE_HWACCEL_AES OFF forces the portable path instead of AES-NI

Leave CERTPP_RNG_FALLBACK off unless you know why you want it. std::random_device is not required by the standard to be cryptographically secure, and on some implementations it has historically returned a constant. With the option off, a missing OS CSPRNG is a hard failure, which is the answer you want.

The hardware-acceleration options exist for reproducing a bug on the portable path and for machines that lack the instructions; the accelerated paths all probe CPUID at runtime, so you do not need to disable them for portability. SSE2 is the exception and is not probed, because it is part of the x86-64 ABI.

Linking against it

The export macro has two halves, and a consumer of the shared build must define one of them:

Macro Who defines it
__COMPILES_LIBCERTPP__ the library's own translation units, never a consumer's
__SHARED_LIBCERTPP__ both the library and every consumer of a shared build

Linking the CMake target certpp::certpp sets this for you. If you are not using CMake, define __SHARED_LIBCERTPP__=1 when you compile against a shared build and leave both undefined for a static one. Getting it wrong on MSVC produces an LNK2019 on a certpp:: symbol rather than anything clearer.

find_package(certpp REQUIRED)
target_link_libraries(your_target PRIVATE certpp::certpp)

Pass -DCMAKE_PREFIX_PATH=<install prefix> if the prefix is not already searched. The installed version file is SameMajorVersion, matching the shared object's SOVERSION.

One MSVC rule that catches people: a static certpp has to be consumed with a matching runtime. Installing a Release build and linking it into a Debug consumer gives _ITERATOR_DEBUG_LEVEL/RuntimeLibrary mismatch errors at link time. That is MSVC's rule, not this library's.

Then one include:

#include <certpp.hpp>

certpp.hpp pulls in the public headers. Two are deliberately excluded: crypto/kem.hpp is the interface with nothing behind it yet, and io/base64.hpp is an empty placeholder — CBase64 lives in utils/base64.hpp, which is included.

Requirements

C++17. Developed and tested on Windows with MSVC 2022; the code itself is portable C++ with no platform API beyond the OS CSPRNG, but other toolchains are not currently part of the test matrix, so treat them as untested rather than unsupported.

No third-party dependency is linked into the library. The only vendored one is doctest, used by the test suite.

What is constant-time, and what is not

This library is not audited. Parts are constant-time by construction and say so in their own documentation; parts explicitly are not, and also say so. Read this table before deploying anywhere an adversary can measure you.

Constant-time:

  • CSecure::equals() / equalsMask() / select() — no early exit. Use equalsMask() with select() when the comparison's outcome is itself a secret; equals() narrows the result to a bool, which is something the caller can then branch on.
  • CSecure::zero() — survives /O2, unlike a memset whose result is unread.
  • CHmac::verify(), and every AEAD's tag comparison inside open().
  • SDsRecord::matches() — recomputes and compares the digest.
  • X25519 — a Montgomery ladder over Fe25519.

Not constant-time, by documented decision:

  • CBigNum — schoolbook arithmetic, and it trims leading zero limbs, so operation cost depends on the values. condSwap() is a plain branch.
  • CGf2m — same stance.
  • The prime curves (CEcCurve) and the binary curves (CEc2Curve), and so ECDSA and the P-256/P-384 ECDH, which are built on them.
  • ML-DSA's rejection sampling — FIPS 204 offers no way to make it so. See docs/pqc-review.md.

If the protocol lets you choose, prefer X25519 over the prime-curve ECDH, and prefer Ed25519 over ECDSA.

What performance to expect

Measured on a loaded 4-core i7-11370H at 3.92 GHz, Release, minimum of three runs of twenty:

Ed25519 sign / verify 7.4 ms / 35.1 ms
ECDSA P-256 sign / verify 7.9 ms / 17.9 ms
ECDSA P-384 verify 40.7 ms
X25519 shared secret 246 µs

The signature figures are slow and known to be slow — an optimized implementation verifies Ed25519 in 50–100 µs, so this is two to three orders of magnitude off. The cause is not the curve arithmetic's shape but its arithmetic backend: X25519's 246 µs in the same build is the control that proves it, because X25519 runs on the dedicated Fe25519 field type while the other curves still run every field operation through CBigNum's schoolbook long division. docs/roadmap.md has the three tiers of the fix.

Budget accordingly: a certificate handshake costs roughly 20 ms of CPU today. Hashing, symmetric encryption and the AEADs are not affected by any of this — those have hardware-accelerated paths and are not the bottleneck.

Error handling

Two conventions, and both are easy to get wrong:

  • ERetCode — ERET_OK is 0, so if (rc) is backwards. Compare against ERET_OK explicitly.
  • bool-returning calls report no reason for a failure. Where a reason matters, there is usually an ERetCode overload.

An output SByteSpan is narrowed by the callee: after the call, the real length is the span's .size, not the sizeof of the buffer you passed. Carry the narrowed size forward.

Before you ship

  • specs/pitfalls.md — ways to call this library wrongly that still appear to work. This is the most valuable page in the repository and the shortest.
  • CCert::verifyBy() checks one signature. Not dates, not basicConstraints, not key usage, not name constraints, not revocation, and not whether the root is one you trust. There is no path validator in this library yet; CCertCollection::buildChain() orders a chain, which is not the same thing as validating one.

Clone this wiki locally