Assurance case¶
This page argues that CryptoService.Sdk meets its security
requirements: what it protects, from whom, where the trust boundaries
are, how the secure design principles are applied and how the common
weaknesses of an HTTP client library are countered. Every claim names
the code or the test that makes it true; paths are relative to the
repository root and tests are in tests/CryptoService.Sdk.Tests/
unless stated. The claim is reviewed with each security review (the
latest is security-review-2026-11.md).
The claim¶
Used as documented, the SDK sends each call only to the base URL its caller configured, with the caller's credentials and nothing else; it never discloses a credential, key or plaintext through its own output; it turns any answer, however malformed, into a typed result or a typed exception within a bounded time; and it never repeats a call that may have changed state on the server. It performs no cryptography, so it cannot weaken one (ADR 0001).
Threat model¶
Assets¶
| Asset | Where it is in the SDK |
|---|---|
| The API key and the bearer token | CryptoServiceClientOptions.ApiKey and Token, copied into Internal/Transport.cs at construction |
| Plaintexts, passwords, exported and unwrapped keys, shared secrets | Request and result models in src/CryptoService.Sdk/Models/, only for the duration of a call |
| The integrity of state on the server (keys, KMS keys, OPAQUE registrations) | Calls that create or delete it, listed in Internal/Idempotency.cs |
| The integrity of the released package | The NuGet package, its symbols, SBOM and checksums, built by .github/workflows/release.yml |
Actors¶
| Actor | Trusted for | Not trusted for |
|---|---|---|
| The calling application | Its options, its requests, the HttpMessageHandler or HttpClient it injects |
Nothing the SDK can check beyond argument validity |
| crypto-server at the base URL | The results of the operations it performs | The shape, size or content of what it sends back |
| The network between them | Nothing | Anything: an attacker may read, drop, delay or rewrite traffic not protected by TLS |
| A redirect target, a proxy, a load balancer | Nothing | Receiving credentials |
| Package registries (nuget.org) and GitHub | Hosting what the release workflow published | Altering it unnoticed: checksums, provenance and signatures make that detectable |
| A contributor, a dependency, a CI action | Nothing by default | Merging, publishing or running with write permissions unreviewed |
Entry points¶
- The public constructors and
CryptoServiceClientOptions(CryptoServiceClient.cs,CryptoServiceClientOptions.cs,RetryOptions.cs). - The typed operation methods (
CryptoServiceClient.*.cs) and the untypedRequestAsync. - Every byte of every answer: status, headers (
Retry-After,Content-Type,Locationwhen a handler followed a redirect) and body (Internal/Decoding.cs). - The build and release pipeline: pull requests, dependencies, the
pinned toolchain and the workflows in
.github/workflows/.
Trust boundaries¶
caller code ──(1)── CryptoService.Sdk ──(2)── HttpClient/handler ──(3)── network ──(4)── crypto-server
│
maintainer ──(5)── GitHub (CI, signed tags, release env) ──(6)── nuget.org ──(7)── consumers
- Caller to SDK. Options are validated and copied once, at
construction (
Transportconstructor): an absolute base URL with no user info, query or fragment; positive timeouts; credentials andtraceparentwithout a line break or NUL. Request objects are checked for null before serialization (ANullRequestIsRefused). - SDK to its HTTP stack. The SDK builds every request itself
(
Transport.BuildRequest) and owns the handler it creates (CryptoServiceClient.CreateHandler: no redirects, no cookies, no automatic decompression). An injected handler orHttpClientis the caller's; the SDK still refuses an answer whose request URI changed (Transport.SendCheckedAsync,ARedirectAnInjectedClientFollowedIsRefused). - Network. Confidentiality and integrity come from TLS with the
platform's certificate validation; the SDK has no option to weaken
it. Plain
httpis accepted for loopback and test servers, andSECURITY.mdtells users to usehttpselsewhere. - crypto-server's answers. Every body is untrusted input: a 2xx
body is decoded by the source-generated contract
(
Internal/CryptoJsonContext.cs,RespectNullableAnnotations,requiredmembers) and any failure becomesCryptoTransportException; an error body is read up to 64 KiB (Decoding.MaxErrorBodyBytes) and anything that is not a problem becomesabout:blank. Both decoders are fuzzed (fuzz/CryptoService.Sdk.Fuzz) and property-tested (PropertyTests). - Maintainer to GitHub. Commits carry a DCO sign-off (
dco.yml) and are signed; release tags are SSH-signed and verified againstKEYS.ascbefore a release is built (release.yml). - GitHub to nuget.org. Publication is by trusted publishing (OIDC)
from the
releaseenvironment, which onlyv*tags can use and which needs the maintainer's approval; no long-lived NuGet key exists (Packaging). - Registry to consumers. Each release carries
SHA256SUMS, a CycloneDX SBOM and a build provenance attestation, and rebuilds byte for byte from its tag (REPRODUCING.md).
Secure design principles¶
The principles of Saltzer and Schroeder, and how the code applies them:
| Principle | How it is applied |
|---|---|
| Economy of mechanism | The SDK is a thin client: one transport (Internal/Transport.cs, under 300 lines), one decoder (Internal/Decoding.cs), one source-generated JSON contract and no cryptography. No third-party runtime dependency (src/CryptoService.Sdk/CryptoService.Sdk.csproj references none). Complexity ceilings (cyclomatic 10, cognitive 15, Halstead 30) are enforced by the build and scripts/halstead.py. |
| Fail-safe defaults | Retries are off by default (NoRetryByDefault); redirects are refused (TheDefaultHandlerRefusesRedirectsAndPoolsConnections); every attempt has a 30-second timeout; TLS validation cannot be turned off; an answer the contract cannot decode is an error, never a partial result (A2xxAnswerThatBreaksTheContractIsATransportError); options that would build a wrong URL or header are refused at construction (ABaseUrlWithUserInfoAQueryOrAFragmentIsRefused, AHeaderValueWithAControlCharacterIsRefused). |
| Complete mediation | Every request, typed or raw, goes through Transport.BuildRequest and Transport.SendCheckedAsync, so the credential, redirect and timeout rules hold for all 59 operations and RequestAsync alike (SendsTheRouteAndDecodesTheAnswer runs every operation through them). Credentials are added only to calls that need them: the /health, /live and /ready probes are sent without (CryptoServiceClient.Meta.cs). |
| Open design | The whole client, its threat model and this argument are public; its security rests on TLS and the server, not on secrecy of the code. |
| Separation of privilege | Publishing needs a signed tag that verifies against KEYS.asc, a v* tag ref, and an approval in the release environment; the build job that runs the tests holds no publishing permission (release.yml). |
| Least privilege | Every workflow defaults to contents: read; write scopes (id-token, attestations, contents: write, security-events, pages) are granted per job, only where needed. Checkouts use persist-credentials: false. The SDK asks for no permission of its host: it writes no file, reads no environment variable and runs no code from the server. |
| Least common mechanism | A client's state is fixed at construction and shared only through the immutable Transport; each call has its own cancellation sources and request (ManyConcurrentCallsShareOneClient). |
| Psychological acceptability | The secure path is the default path: new CryptoServiceClient(options) gets the hardened handler; credentials print as set (redacted) (NoDescriptionShowsACredential), so logging the options or the client is safe. |
Common weaknesses¶
The weaknesses of the CWE Top 25 and the OWASP Top 10 that apply to an HTTP client library, and what counters each:
| Weakness | Counter in the SDK | Evidence |
|---|---|---|
| CWE-20 Improper input validation | Options checked at construction; request objects checked for null; the method and path of RequestAsync checked |
TheOptionsAreChecked, ANullRequestIsRefused, RequestAsyncChecksItsArguments |
| CWE-113 / CWE-93 Header injection (CRLF) | API key, token, traceparent and the raw media type are refused if they hold CR, LF or NUL, because HttpClient sends values added without validation as they are |
Transport.CheckHeaderValue; AHeaderValueWithAControlCharacterIsRefused, RequestAsyncChecksItsArguments |
| CWE-200 / CWE-532 Exposure of sensitive information, including in logs | The SDK logs nothing; exception messages name the status, problem type and title only, and the server's detail stays in Problem; options and the client describe credentials as set or unset and redact user info; models are classes whose ToString() is the type name |
CryptoApiException.Describe, CryptoServiceClientOptions.ToString; NoDescriptionShowsACredential, TheOptionsNeverShowTheBaseUrlsUserInfo |
| CWE-295 Improper certificate validation | The SDK never sets a certificate callback and has no option to | CryptoServiceClient.CreateHandler; ADR 0002 |
| CWE-319 Cleartext transmission of sensitive information | TLS is the transport for any non-loopback server; http remains possible for loopback and tests, documented in SECURITY.md |
Residual risk, see below |
| CWE-601 Open redirect / OWASP A10 SSRF-style credential forwarding | Redirects refused by the default handler, and detected and refused when an injected handler follows one, so a credential never goes to another origin | ARedirectAnswerIsAnErrorNotFollowed, ARedirectAnInjectedClientFollowedIsRefused |
| CWE-400 / CWE-770 Uncontrolled resource consumption | Per-attempt timeout and optional call deadline; error bodies capped at 64 KiB; no automatic decompression; retries bounded by MaxRetries and MaxDelay, a Retry-After beyond MaxDelay ends the call |
AnOversizedErrorBodyIsNotRead, TheDeadlineEndsTheCallAndIsNotRetried, ARetryAfterLongerThanMaxDelayEndsTheCall |
| CWE-502 Deserialization of untrusted data | Source-generated System.Text.Json into fixed types: no polymorphic type handling, no reflection, required and nullability enforced |
Internal/CryptoJsonContext.cs; fuzz target success; TheSynchronousDecoderMatchesTheStreamingOne |
| CWE-754 / CWE-755 Improper handling of exceptional conditions | Whatever the server sends, a call ends in a typed result, CryptoApiException or CryptoTransportException (or OperationCanceledException for the caller's own token); the problem parser never throws. An exception an injected handler raises that is not a transport failure propagates unchanged rather than being disguised |
Fuzz targets problem and success; ABodyThatIsNotAProblemBecomesAboutBlank, AnUnexpectedHandlerFailurePropagatesUnwrapped |
| CWE-362 Race condition | Immutable client; per-call state only | ManyConcurrentCallsShareOneClient |
| Non-idempotent replay (OWASP API: business-logic integrity) | A stateful call is retried only after 429 or 503, when the server did not act; never after 504, a timeout or a lost connection | Internal/Idempotency.cs; AStatefulCallIsRetriedOnlyWhenTheServerDidNotAct, AStatefulCallIsNotRetriedAfterAConnectionFailure, TheRetrySafetyTableMatchesTheReferenceSdk |
| CWE-798 Hard-coded credentials | None in the library; tests, examples and CI use synthetic values made up for the run | AGENTS.md; CI's conformance job |
| CWE-787 / CWE-125 / CWE-416 Memory safety | Managed code only, no unsafe, no native interop |
src/CryptoService.Sdk/ |
| OWASP A02 Cryptographic failures | No cryptography in the client; every primitive is the server's | ADR 0001 |
| OWASP A06 Vulnerable and outdated components / CWE-1395 | No runtime dependency; build, test and fuzz packages pinned exactly and locked with content hashes; dotnet list package --vulnerable fails CI; Dependabot watches NuGet and the actions |
Directory.Packages.props, packages.lock.json, ci.yml audit job, .github/dependabot.yml |
| OWASP A08 Software and data integrity failures / CWE-494 | Actions pinned by commit SHA; signed tags verified against KEYS.asc; trusted publishing; checksums, SBOM and provenance; reproducible rebuild |
.github/workflows/release.yml, REPRODUCING.md |
| OWASP A09 Security logging and monitoring failures | Not the SDK's to log; it gives callers what they need to log safely: status, problem type, TimedOut, and a traceparent to correlate with the server's logs |
CryptoApiException, CryptoTransportException.TimedOut, AGeneratedTraceparentIsFreshAndWellFormed |
Assumptions and residual risks¶
- The server is the one the caller meant. The SDK cannot tell a
genuine crypto-server from an impostor at the configured URL; TLS
with certificate validation is what establishes that. Over plain
httpto a non-loopback host, credentials and data are exposed to the network: documented, not prevented. - A 2xx body is decoded as it streams, without a size cap. A hostile server could send a very large body; the per-attempt timeout bounds how long it can do so, not how much memory it uses. Results such as batch signatures have no natural size limit, so a cap would break legitimate use. Accepted in the security review.
- Secrets live in managed strings for the life of the options and the client, and in request and result objects for a call; .NET offers no reliable way to wipe them. A process memory dump exposes them, as it would for any .NET HTTP client.
- An injected
HttpClientor handler is the caller's. If it turns off certificate validation or adds headers, the SDK cannot see it; redirect refusal is the one rule it still enforces.
Keeping the case true¶
The tests named above run on every change (ci.yml, 100 % line and
branch coverage), the fuzz targets run on every change and weekly
(fuzz.yml), and CodeQL and OpenSSF Scorecard run on the repository.
A change to the transport, the options, the decoders or the release
workflow updates this page in the same pull request.