crypto-service-sdk 0.0.40

Async and blocking typed client for the Crypto Service REST API (crypto-server v2)
Documentation

Contents

Getting started

  • Install: from crates.io, or the git repository
  • Requirements: toolchain floor, platforms, a server
  • Quick Start: a digest and a typed error in a few lines

The Crypto Service ecosystem

Library reference

Operational


Install

As a Rust library

[dependencies]
crypto-service-sdk = "0.0.40"
tokio = { version = "1.49", features = ["macros", "rt-multi-thread"] }

0.0.40 is the first release published to crates.io. Before it is out, depend on the repository instead: crypto-service-sdk = { git = "https://github.com/sebastienrousseau/crypto-service-sdk-rust" }. Add features = ["blocking"] for blocking::Client. HTTPS uses rustls (no OpenSSL) with the platform's trust store.


Requirements

  • Rust 1.85 or newer (rust-version in Cargo.toml), built and tested in CI on 1.85.0 and stable on Linux (toolchain policy).
  • A crypto-server to talk to. CI runs the conformance kit in conformance/ against crypto-server at the commit in ci/server.ref.
  • Tokio for the async client. The blocking client brings its own runtime and needs none from the caller.

Quick Start

use crypto_service_sdk::{Client, Error, HashAlgorithm, HashRequest};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let url = std::env::var("CRYPTO_SERVICE_URL").expect("set CRYPTO_SERVICE_URL");
    let key = std::env::var("CRYPTO_SERVICE_API_KEY").expect("set CRYPTO_SERVICE_API_KEY");
    let client = Client::builder(url).api_key(key).build()?;

    let result = client
        .hash(&HashRequest {
            algorithm: HashAlgorithm::Sha256,
            data: "abc".into(),
        })
        .await?;
    println!("{} {}", result.algorithm, result.digest);
    Ok(())
}

hash posts to POST /v2/hash and returns the digest as Hex bytes. Every failure is an Error: a non-2xx answer is Error::Api with the server's RFC 9457 problem (type, title, status, detail, code, errors[]), and no answer at all is Error::Transport.

use crypto_service_sdk::{Client, Error, SignRequest};

#[tokio::main]
async fn main() -> Result<(), Error> {
    let url = std::env::var("CRYPTO_SERVICE_URL").expect("set CRYPTO_SERVICE_URL");
    let key = std::env::var("CRYPTO_SERVICE_API_KEY").expect("set CRYPTO_SERVICE_API_KEY");
    let client = Client::builder(url).api_key(key).build()?;

    let request = SignRequest {
        key_id: "k_AAAAAAAAAAAAAAAAAAAAAA".into(),
        message: "pay 10 EUR".into(),
    };
    match client.sign(&request).await {
        Err(Error::Api(api)) => {
            println!("{} {} {:?}", api.status, api.problem.kind, api.code());
            assert_eq!(api.code(), Some("KEY_NOT_FOUND"));
        }
        other => panic!("expected a problem, got {other:?}"),
    }
    Ok(())
}

The Crypto Service ecosystem

This crate is one of the Crypto Service SDKs. Crypto Service has one engine, crypto-server, and thin typed clients per language that all pass one shared conformance kit. The SDKs release in lockstep at one version; this crate's first release is 0.0.40.

Component Purpose Use case
crypto-service crypto-server and 18 npm packages (library, server, CLI, SDK, middleware, KMS, MCP, LSP, CBOM and more) The server this client calls
crypto-service-sdk-python Typed Python client Call crypto-server from Python
crypto-service-sdk-go Typed Go client Call crypto-server from Go
crypto-service-sdk-java Typed Java client Call crypto-server from the JVM
crypto-service-sdk-dotnet Typed .NET client Call crypto-server from .NET
crypto-service-sdk-cpp Typed C++ client Call crypto-server from C++
crypto-service-sdk-rust Typed async and blocking Rust client Call crypto-server from a Rust service
crypto-service.co Website and documentation Read about the service

Capabilities at a glance

Area Capability Status
Probes and meta root(), health(), live(), ready(), algorithms() Supported
Compliance documents get_dora_compliance(), get_cbom() (CycloneDX 1.6); informational, not an assessment Supported
Hashing and MACs hash(), mac(), mac_verify() Supported
Key derivation and passwords kdf(), password_hash(), password_verify(), password_encrypt(), password_decrypt() Supported
Symmetric encrypt(), decrypt(), secretbox_seal(), secretbox_open(), key_wrap(), key_unwrap() Supported
Server-held keys generate_key_pair(), export_key(), keys_delete(), sign(), verify(), stream_sign(), stream_verify() Supported
Post-quantum ML-KEM-768, the X25519 + ML-KEM-768 hybrid, ML-DSA, SLH-DSA, ISO 20022 dual signatures Supported
Public-key encryption sealed boxes (classical and hybrid), multi-recipient, post-quantum streams, HPKE Supported
KMS kms_create_key(), kms_encrypt(), kms_decrypt(), kms_generate_data_key(), kms_wrap(), kms_unwrap() Supported
OPAQUE the four server-side registration and login steps Supported
Low level send_raw(): any method and path, any status Supported
v1 OpenPGP routes, /metrics Deprecated (v1 sunsets 2027-01-01) or operational Not wrapped; use send_raw()

59 of 59 v2 operations have a method, plus the four probes; see docs/ARCHITECTURE.md for how they are built.


Ecosystem comparison

The SDKs share one method surface, one resilience contract and one conformance kit, run against a live crypto-server in each SDK's CI.

Project Language (minimum) Conformance kit in CI Async and blocking
crypto-sdk (TypeScript, in crypto-service) Node 24 Reference runner Async
crypto-service-sdk-rust Rust 1.85 Yes Both
Other Crypto Service SDKs See each README Yes See each README
Raw HTTP Any No Yours to write

See docs/COMPARISON.md for the evidence and the complete matrix.


Benchmarks

Criterion benchmarks with the scenario names every SDK shares: encode_request, decode_response and decode_problem measure the client-side cost with no network, and round_trip_hash a loopback round trip against CRYPTO_SERVICE_URL. No numbers are published yet; they will be generated into docs/BENCHMARKS.md with their environment.


Features

  • Client (src/client.rs, src/builder.rs): Client::builder(url) with .api_key(..) (sent as x-api-key), .token(..) (Bearer), .timeout(..) (per attempt, default 30 s), .deadline(..) (whole call), .retry(RetryPolicy), .traceparent(..) and .transport(..). One async method per operation. Clone + Send + Sync; clones share one connection pool. Every request sends User-Agent: crypto-service-sdk-rust/0.0.40.
  • blocking::Client (feature blocking): the same methods without async, on a runtime the client owns.
  • Types (src/types/): one request and one answer type per operation, with the encodings the OpenAPI document states: Hex and Base64 for binary values, SecretBytes and SecretString for keys, passwords and plaintexts (zeroised on drop, redacted in Debug).
  • Error (src/error.rs): Api(ApiError) with the RFC 9457 Problem, Transport(TransportError) with timed_out, Decode(DecodeError) naming only the position of a fault, and Config for options that cannot work.
  • RetryPolicy (src/retry.rs): off by default; full-jitter backoff; Retry-After honoured up to the maximum delay; calls that create or delete server state retried only after 429 or 503.
  • Transport (src/transport.rs): the HTTP exchange, replaceable for tests; the default is reqwest with rustls, HTTP/2 and gzip.

Configuration

Option Default Set with
Base URL none Client::builder("https://crypto.example.com")
API key none .api_key(key) (x-api-key)
Bearer token none .token(jwt)
Timeout per attempt 30 seconds (DEFAULT_TIMEOUT) .timeout(Duration); Duration::ZERO turns it off
Deadline per call none .deadline(Duration)
Retries none (max_retries 0, 200 ms initial, 2 s maximum delay) .retry(RetryPolicy::new().max_retries(3))
traceparent none .traceparent(Traceparent::Auto) or Traceparent::Fixed(..)
HTTP stack ReqwestTransport .transport(Arc<dyn Transport>)

The client reads no environment variables. The tests, examples and benchmarks read CRYPTO_SERVICE_URL, CRYPTO_SERVICE_API_KEY and, for the conformance kit, CRYPTO_SERVICE_JWT_SECRET.


Examples

Each example exits non-zero when the server does not answer as it expects; CI's conformance job runs them all:

cargo run --example hash
cargo run --example ml_kem
Example Shows
hash hash(): SHA-256 of abc
aead encrypt() and decrypt(), an XChaCha20-Poly1305 round trip
sign_verify a server-held Ed25519 key: generate_key_pair(), sign() by keyId, verify(), keys_delete()
ml_kem a server-held ML-KEM-768 key: encapsulate to it, decapsulate by keyId
errors Error::Api with a problem and its code, a validation problem's errors[], Error::Transport
concurrent one client shared by eight Tokio tasks
blocking blocking::Client and a KMS round trip with encoding: hex

When not to use Crypto Service

  • You need the cryptography in your own process. This crate performs no cryptography; every operation is an HTTP call to crypto-server. If keys must never leave the caller, or the network is not acceptable on the hot path, use a local library instead.
  • You cannot run or reach a crypto-server. The work happens there.
  • You need the v1 OpenPGP routes. They are deprecated and sunset on 2027-01-01; this crate does not wrap them (nor /metrics), though send_raw() reaches them.
  • You need the client half of OPAQUE. The SDK carries the messages; blinding, KE1 and KE3 stay with the caller.

Development

cargo test --locked --all-features

make check runs rustfmt, clippy (pedantic, -D warnings), the build, the tests at 100% line and region coverage (cargo-llvm-cov), rustdoc with warnings denied, cargo deny, the complexity ceilings (cyclomatic 10, cognitive 15, Halstead difficulty 30, 60 lines per function, 500 per file), the version check and the package contents check; make coverage-branch adds 100% branch coverage on nightly. With a server, make conformance runs the kit, the live tests, every example and every block of this README; make regression starts a server itself. make fuzz runs the two cargo-fuzz targets. See DEVELOPMENT.md for every gate and its CI job.


Security

The crate has no unsafe code. TLS verification is always on (rustls, the platform's trust store) and cannot be turned off; redirects are refused, so credentials never follow a Location. The API key and token are redacted in Debug and marked sensitive in the HTTP stack. No error message carries a credential, key, plaintext or body: decode errors name only a line and column. Keys, passwords and plaintexts are held in zeroising types, and a 2xx body is zeroised after decoding; request bodies handed to the HTTP stack are not. Response bodies are read up to 64 MiB. The decoding paths are fuzzed, every dependency is checked by cargo deny, and CodeQL and OpenSSF Scorecard run on main; releases carry an SBOM and build provenance.

Report vulnerabilities according to SECURITY.md.


Documentation

API reference (docs.rs) · Developer docs · Ecosystem map

Also: Architecture · Decision records · Conformance kit · Changelog · Policies · Packaging · Roadmap · Support · Governance · Agent rules


Stability guarantees

The project is pre-1.0 and versions advance in 0.0.1 steps, in lockstep with the Crypto Service SDKs. The breaking axis is the public Rust API: method signatures, the Error variants, the options and the request and answer types; cargo-semver-checks guards it against the last crates.io release from 0.0.40 on. Answer structs and enums are #[non_exhaustive]. The client covers the v2 API of crypto-server at the commit in ci/server.ref; v1 (deprecated, sunset 2027-01-01) and /metrics are outside it. The internals feature and crypto_service_sdk::fuzzing are not public API. The Rust floor moves only as described in the toolchain policy.


License

This project is dual-licensed under either:

at your option. Dependencies keep their own licences.