Assurance case¶
This document argues that crypto-service-sdk-cpp meets its security requirements: what it protects, from whom, where the trust boundaries are, how secure design principles are applied, and how the common weaknesses of an HTTP client library written in C++ are countered. Each claim points at the code that implements it and the test or CI job that keeps it true. The security policy has the reporting process and the short threat table; the security review of November 2026 checked this case against the code and records what it found.
The claim¶
Used as documented, the SDK sends each request only to the server the
caller configured, over verified TLS when the URL is https://; it
never discloses the caller's credentials or data through its own
output; it never repeats a request that may already have changed
server state; and malformed or hostile responses end in a typed error,
never in memory corruption or a crash. The SDK performs no cryptography
itself, so the strength of every cryptographic result is crypto-server's
responsibility, not this library's.
Scope¶
In scope: the library (include/, src/), its build and install
rules, the release pipeline and the CI that guards them. Out of scope:
crypto-server and its cryptography
(its own advisories),
libcurl and the TLS library, which come from the operating system, and
the security of the application that embeds the SDK.
Assets¶
| Asset | Where it lives in the SDK | Why it matters |
|---|---|---|
| Credentials: API key and bearer token | ClientOptions::api_key, ClientOptions::token; copied into detail::Settings::credentials (src/settings.cpp, settle) |
They authorise every operation on the caller's keys |
| Request payloads: plaintexts, passwords, key material, KMS data keys | Request structs, the JSON body in HttpRequest::body |
Confidential by definition in a cryptography API |
| Results: ciphertexts, signatures, shared secrets, unwrapped keys | Result structs decoded in src/wire.cpp |
Confidentiality and integrity of the caller's data |
| Correct server state | Keys created or deleted on the server | A duplicated keys/generate or keys/delete is a real side effect |
| The caller's process | Memory and threads the SDK runs in | A memory-safety bug in a library is the host application's bug |
| The released artefacts | Source archive, SBOM, SHA256SUMS, provenance attestation |
What consumers build from |
Actors¶
| Actor | Trust | What they control |
|---|---|---|
| The calling application and its developer | Trusted | ClientOptions, every request, custom Transport implementations |
crypto-server at base_url |
Trusted to perform the cryptography and authorisation; its responses are still parsed defensively | Response status, headers and bodies |
| The network, proxies and middleboxes | Untrusted | Anything on a plain http:// connection; availability on any connection |
A hostile or compromised server, or one impersonated on http:// |
Untrusted | Arbitrary status codes, headers, bodies and timing |
| Upstream projects: nlohmann/json, GoogleTest, Google Benchmark, libcurl | Trusted at a pinned version | Code compiled into the library or its tests |
| GitHub Actions and the maintainer's signing key | Trusted | The release build and its signatures |
| Pull request authors | Untrusted until reviewed | Code and workflow changes proposed to the repository |
Entry points¶
- The public API (
include/crypto_service/):ClientOptions, the typed operations onClientandAsyncClient, the rawrequest(),describe(), and theTransportandAsyncTransportinterfaces a caller may implement. - HTTP responses: the status, headers and body a transport returns,
parsed by
src/curl_common.cpp(headers),src/problem.cpp(RFC 9457 problems),src/wire.cppandsrc/codec.cpp(success bodies) andsrc/retry.cpp(Retry-After). - The build: the CMake files and the archives they fetch.
- CI and release: the workflows in
.github/workflows/, and the crypto-server commit inci/server.refthat CI builds.
The library reads no environment variable, file or command line of its
own. libcurl does read the standard proxy variables (http_proxy,
HTTPS_PROXY, NO_PROXY and the like); see the network boundary
below.
Trust boundaries¶
caller (trusted)
| ClientOptions, requests validated: settle(), build()
v
SDK -- HttpRequest --> Transport (libcurl, or the caller's own)
^ | TLS verify on, no redirects, http/https only
| typed result or error v
+--- parsed defensively -- network (untrusted) -- crypto-server
(trusted for crypto)
build: CMake -- SHA-256-pinned archives -- GitHub release downloads
CI: pull request (untrusted) -- read-only token -- signed tag -- release
| Boundary | What crosses it | How it is guarded |
|---|---|---|
| Caller to SDK | Options, request structs, raw paths and headers | settle() and build() in src/settings.cpp validate the base URL, credentials, timeouts, retry ranges, traceparent, method, path and every header before anything is sent; the request text must be valid UTF-8 (encode in src/wire.cpp) |
| SDK to network | The HTTP request | set_security() in src/curl_common.cpp sets, on every transfer, CURLOPT_FOLLOWLOCATION 0, CURLOPT_SSL_VERIFYPEER 1, CURLOPT_SSL_VERIFYHOST 2 and CURLOPT_PROTOCOLS_STR "http,https"; no option turns them off. Proxies from libcurl's environment variables are honoured, as for any libcurl program: an HTTPS request goes through a proxy as a CONNECT tunnel with the server's certificate still verified, and a plain http:// request is visible to the proxy |
| Network to SDK | Status, headers, body | Redirects become TransportError (refuse_redirect); problem bodies are parsed with exceptions off (problem_of); success bodies must have the documented shape or raise TransportError naming the member, never its value (decode) |
| SDK to crypto-server | Authorisation and cryptography | The server enforces scopes, quotas and key sizes; the SDK sends credentials only on operations that need them (Route::anonymous for /health, /live, /ready; Settings.BuildHeaders) |
| Registries and upstream sources to the build | nlohmann/json, GoogleTest, Google Benchmark archives | URL_HASH SHA256 in the CMake files fails the configure step on any change; scripts/osv-check.py checks the pinned tags against OSV on every change and weekly |
| Pull requests to CI | Code, workflows, ci/server.ref |
Workflows run on pull_request (never pull_request_target) with a read-only token and persist-credentials: false; actions are pinned by commit SHA; ci/server.ref must be a 40-character commit SHA before it is fetched |
| CI to release | The tag, the archive, the SBOM | Only a signed, annotated tag whose signature verifies against KEYS.asc and which is the commit being built publishes, whether the run came from a tag push or a dispatch (scripts/verify-release-tag); the version must be digits and dots; the files are rebuilt twice and compared, attested with GitHub build provenance, and published from the release environment |
Secure design principles¶
The principles of Saltzer and Schroeder, and how each shows up in the code.
| Principle | How it is applied |
|---|---|
| Economy of mechanism | The SDK is a thin client: every operation is one HTTP call, and the library contains no cipher, hash, signature or KDF (ADR 0001). Hex and base64 (src/encoding.cpp) are the only byte transforms. Two transports share one setup function (prepare in src/curl_common.cpp), so the security options are set in one place. |
| Fail-safe defaults | TLS verification is on and cannot be disabled; redirects are refused; retries are off (RetryOptions::max_retries = 0); unknown routes are treated as idempotent only when they are not on the stateful list, and the stateful list matches by substring, so a new keygen path is refused a risky retry rather than allowed one (is_idempotent in src/settings.cpp). A response that does not decode is an error, never a default-constructed result. |
| Complete mediation | Every request, typed or raw, goes through build(), which validates the method, path and headers, and through one execute() (src/client.cpp) or one event loop (src/async_client.cpp) that applies the timeout, deadline, cancellation, retry rule and redirect refusal. There is no second path to the transport. |
| Least privilege | Health probes send no credentials (Route::anonymous). CI jobs hold contents: read; only the jobs that need it get security-events, id-token, attestations, pages or contents: write, and the release publish job runs in a protected environment. |
| Separation of privilege | Publishing a release needs a signed tag that verifies against KEYS.asc and the release environment; a pull request alone cannot publish. (A second human reviewer is not yet available; see GOVERNANCE.md.) |
| Least common mechanism | Each Client owns its own libcurl easy handle and each AsyncClient its own multi handle and thread; nothing is shared between clients except libcurl's process-wide initialisation, done once (ensure_curl_global). |
| Open design | The source, the threat model, this case and the review are public; security rests on TLS and the server's keys, not on secrecy of the client. |
| Psychological acceptability | Secure behaviour needs no configuration: a caller who only sets base_url and a credential gets verified TLS, no redirects, bounded timeouts and redacted describe() output. Errors are typed (ApiError, TransportError, CancelledError) so callers can handle them without parsing messages. |
Common weaknesses and how they are countered¶
Mapped to the 2024 CWE Top 25 and the OWASP Top 10 categories that apply to an HTTP client library. Web-application weaknesses with no counterpart in a client library (cross-site scripting, SQL injection, CSRF, file upload) are omitted.
| Weakness | Counter | Evidence |
|---|---|---|
| Out-of-bounds read and write, use after free, NULL dereference (CWE-787, CWE-125, CWE-416, CWE-476) | Standard containers and std::string_view only; RAII owners for every libcurl handle and header list (EasyHandle, HeaderList, MultiDeleter); a null transport is rejected in the client constructors |
Unit tests under ASan and UBSan with GCC and Clang (ci.yml, build); libFuzzer with ASan and UBSan on both response parsers (fuzz.yml); _GLIBCXX_ASSERTIONS bounds checks in the hardened builds; Client.NullTransportIsRejected, AsyncClient.InvalidArguments |
| Integer overflow (CWE-190) | Retry-After delta-seconds above nine digits saturate instead of overflowing (delta_seconds in src/retry.cpp); timeouts and deadlines are capped at 24 hours, so the call budget's clock arithmetic stays in range |
Retry.RetryAfterValues, Settings.TimeoutAndDeadlineAreAtMostADay |
| Improper input validation (CWE-20) | settle() and build() validate every option and request part; the decoder checks types, integer ranges and hex and base64 alphabets and canonical padding |
Settings.*, Codec.DecodeFailuresNameTheMember, Codec.OtherDecodeFailures, Encoding.*RejectsMalformedInput |
| CRLF injection and HTTP request splitting (CWE-93, CWE-113) | Credentials, the traceparent, extra header names and values, the base URL and the path are rejected if they contain a control character | Settings.CredentialsTimeoutsAndTraceparent, Settings.BuildRejectsBadPathsMethodsAndHeaders, Settings.BaseUrl |
| Exposure of sensitive information, log injection (CWE-200, CWE-532, CWE-117) | The SDK never writes to a stream. ApiError::what() names only the status and the problem type, with control characters replaced; decode errors name the member, never the value; describe() prints <redacted> for credentials and user information |
Problem.ApiErrorMessageNamesStatusAndTypeOnly, Problem.ApiErrorMessageReplacesControlCharactersInTheType, Settings.DescribeRedactsCredentials; the response fuzzer aborts if a body appears in an error message |
| Improper certificate validation (CWE-295) | Peer and host-name verification always on (set_security) |
CurlTransport.TlsIsVerifiedAndAPlainServerFails shows an https:// URL never falls back to plain text; there is no test with an untrusted certificate yet (review finding F-06) |
| Cleartext transmission (CWE-319) | https:// verified as above. http:// is accepted for any host, for local development and private networks, and documented as unsafe for credentials elsewhere |
SECURITY.md threat table; accepted in the review (F-04) |
| Credentials in URLs (CWE-598) | A base_url with user information, a query or a fragment is rejected |
Settings.BaseUrl |
| Server-side request forgery and open redirect (CWE-918, CWE-601) | The destination is only ever base_url plus a validated path; 3xx responses are errors and Location is never followed |
Client.RedirectsAreRefused, AsyncClient.RedirectsAreRefused, CurlTransport.RedirectsAreNotFollowed |
| Uncontrolled resource consumption (CWE-400) | Per-attempt timeout (default 30 s) and optional deadline; at most 100 retries with delays capped at one hour; Retry-After beyond max_delay ends retrying; cancellation within about 10 ms on AsyncClient. Response bodies are not size-limited (review finding F-03, accepted) |
Client.DeadlineBoundsTheAttemptTimeout, Retry.RetryAfterIsHonouredUpToMaxDelay, Settings.RetryRanges |
| Race conditions (CWE-362) | AsyncClient state touched by callers is guarded by one mutex; everything else belongs to the loop thread; cancel tokens are atomics |
make tsan (ci.yml, tsan): AsyncClient.ManyThreadsShareOneClient, AsyncClient.DestructionCancelsCallsInFlight, CurlMultiTransport.CancelAndDestroyWithTransfersInFlight |
| Deserialisation of untrusted data (CWE-502) | Bodies are parsed as JSON by nlohmann/json with exceptions off, then mapped onto fixed structs; no polymorphic or code-bearing format | Decode.ShapeErrorsAreTransportErrors, the two fuzz targets |
| Duplicated side effects (business-logic flaw) | Stateful routes are retried only after 429 or 503, never after a 504 or a lost connection (ADR 0004) | Client.StatefulCallsAreNotRetriedAfterLostConnectionOr504, AsyncClient.StatefulCallsAreNotRetriedAfterALostConnection, Retry.StatefulRoutes |
| Use of weak cryptography, weak randomness (CWE-327, CWE-330; OWASP A02) | No cryptography in the client. std::mt19937_64 is used only for traceparent ids and retry jitter, which are not secrets |
src/settings.cpp (make_traceparent), src/retry.cpp (jittered) |
| Hard-coded credentials (CWE-798) | None in the library; CI and tests use values marked synthetic | ci.yml (conformance job comment), AGENTS.md data rule |
| OS command injection (CWE-78) in the pipeline | The release version must match ^[0-9]+\.[0-9]+\.[0-9]+$, and step outputs reach scripts through environment variables, not ${{ }} interpolation |
release.yml (Resolve the version); review finding F-02 |
| Vulnerable and outdated components (CWE-1104; OWASP A06) | Archives pinned by SHA-256; OSV checked on every change and weekly; Dependabot for actions and the manual's Python requirements; libcurl from the OS | osv.yml, scripts/osv-check.py, .github/dependabot.yml |
| Software and data integrity failures (CWE-494; OWASP A08) | Signed commits and tags, SHA-pinned actions, the vendored conformance kit checked against its SHA256SUMS, reproducible release files with provenance attestations |
Kit.VendoredFilesMatchTheirChecksums, release.yml, REPRODUCING.md |
Compiler hardening¶
The SDK is distributed as source: the release contains no binary, and
every consumer compiles it with their own toolchain and flags. The
CMake files therefore set warnings only (-Wall -Wextra -Wpedantic, and
-Werror when asked), and impose no hardening flags, for three
reasons:
- The consumer, or their distribution, owns the code-generation policy.
Debian and Ubuntu (
dpkg-buildflags, and Ubuntu's GCC defaults), Fedora (redhat-rpm-config) and others already inject a hardening set; a library adding its own on top can conflict with it, for example by redefining_FORTIFY_SOURCEat a different level. _FORTIFY_SOURCEneeds optimisation, and-fcf-protectionand-fstack-clash-protectionare target-specific, so a flag set fixed in the library would be wrong for some builds (Debug, MSVC, non-x86).- Flags set on the library target would cover only its own objects, not the application that links it, which gives a false sense of coverage.
What the project does instead is check that the recommended set works.
The CI build matrix compiles and tests the library with GCC and with
Clang using
-O2 -U_FORTIFY_SOURCE -D_FORTIFY_SOURCE=3 -D_GLIBCXX_ASSERTIONS
-fstack-protector-strong -fstack-clash-protection -fcf-protection
-Wl,-z,relro,-z,now
under -Werror (jobs gcc-hardened and clang-hardened), so a consumer
can apply them through CMAKE_CXX_FLAGS and CMAKE_EXE_LINKER_FLAGS
knowing the build stays warning-free and the tests pass. The unit tests
also run under ASan, UBSan and TSan, and the parsers under libFuzzer.
Supply chain and pipeline¶
- Dependencies. One run-time dependency besides the system libcurl: nlohmann/json, header-only, fetched from its release archive and checked against a SHA-256. GoogleTest and Google Benchmark are fetched the same way and never linked into the library. The SBOM lists exactly these pins.
- Static analysis. CodeQL (
security-extended) and clang-tidy run on every pull request; OpenSSF Scorecard runs weekly. - Release integrity. See the CI-to-release boundary above and REPRODUCING.md.
Residual risks¶
These are known and accepted; the security review explains each.
- Response bodies are buffered whole with no size limit, and compressed responses are decompressed, so a hostile or compromised server can make a call use a lot of memory (F-03).
http://is accepted for any host; credentials sent that way are visible on the network (F-04).- Credentials and payloads live in ordinary
std::stringandstd::vectormemory and are not wiped after use (F-05). - A caller-supplied
Transportreplaces libcurl and with it every network guarantee above; it is the caller's code.
Keeping the case true¶
Each claim names a test, a fuzz target or a CI job, and every one of those runs on every pull request, so a change that breaks a claim fails CI. AGENTS.md forbids the changes that would invalidate the case outright (an option to disable TLS verification, following redirects, relaxing the stateful-route rule). This document is revisited at each security review and whenever a trust boundary changes.