Repository navigation
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.
cmake -S . -B build
cmake --build build --config DebugA 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.
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.
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.
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. UseequalsMask()withselect()when the comparison's outcome is itself a secret;equals()narrows the result to abool, which is something the caller can then branch on. -
CSecure::zero()— survives/O2, unlike amemsetwhose result is unread. -
CHmac::verify(), and every AEAD's tag comparison insideopen(). -
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.
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.
Two conventions, and both are easy to get wrong:
-
ERetCode—ERET_OKis 0, soif (rc)is backwards. Compare againstERET_OKexplicitly. -
bool-returning calls report no reason for a failure. Where a reason matters, there is usually anERetCodeoverload.
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.
-
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, notbasicConstraints, 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.