Expand description
Typed async and blocking client for the Crypto Service REST API.
crypto-server exposes hashing, MACs, key derivation, AEAD, server-held signing and decryption keys, ML-KEM, ML-DSA, SLH-DSA, HPKE, KMS and OPAQUE over HTTP. This crate is a thin client for its v2 API: one method per operation, and no cryptography of its own. Every operation is an HTTP call to the server.
use crypto_service_sdk::{Client, HashAlgorithm, HashRequest};
let client = Client::builder("http://127.0.0.1:3000")
.api_key("synthetic-api-key-0000000000000000")
.build()?;
let digest = client
.hash(&HashRequest {
algorithm: HashAlgorithm::Sha256,
data: "abc".into(),
})
.await?;
println!("{}", digest.digest);A non-2xx answer becomes Error::Api with the server’s RFC 9457
Problem; no answer at all becomes Error::Transport. Retries are
off unless a RetryPolicy turns them on, and a call that creates or
deletes server state is never retried after the server may have acted
on it. Keys, passwords and plaintexts travel in SecretBytes and
SecretString, which are zeroised on drop and redacted in Debug.
With the blocking feature, blocking::Client offers the same methods
without async.
Re-exports§
pub use http;
Modules§
- blocking
- The blocking client (the
blockingfeature).
Structs§
- Algorithms
- The answer of
GET /v2/algorithms: algorithm names by category. - ApiError
- A non-2xx answer, with its RFC 9457 problem.
- Argon2
Params - Argon2id parameters: memory in KiB, passes and lanes.
- Base64
- Bytes the API carries as standard base64 with padding
(
contentEncoding: base64): AEAD, secretbox, sealed-box, stream, password-encryption and AES key wrap output. - Cbom
- The answer of
GET /v2/compliance/cbom: a CycloneDX 1.6 cryptographic bill of materials (application/vnd.cyclonedx+json), not wrapped indata. Informational input for CRA and DORA work. - Cbom
Component - One component of the CBOM.
- Cbom
Property - A name and value pair of a CBOM component.
- Ciphertext
- A ciphertext and its algorithm.
- Client
- A client for one crypto-server.
- Client
Builder - Options for a
Client; start withClient::builder. - Decode
Error - A 2xx body that did not decode. It names where the fault is, never the value found there, which could be a key or a plaintext.
- Decrypt
Request POST /v2/decrypt: opens whatEncryptRequestproduced.- Deleted
Key - The answer of
POST /v2/keys/delete. - Deprecation
Entry - One algorithm and its suggested sunset.
- Dora
Compliance - The answer of
GET /v2/compliance/dora: a self-reported inventory, not a compliance assessment under Regulation (EU) 2022/2554. - Empty
- A request without parameters, sent as
{}. - Encoding
Error - A string that is not valid hex or base64.
- Encrypt
Request POST /v2/encrypt: XChaCha20-Poly1305 under a caller-held key.- Envelope
Signature - One signature of an ISO 20022 envelope.
- Exported
Key - The answer of
POST /v2/keys/export: the key pair’s private parts. Which members are present depends on the algorithm. A member this version does not name is dropped rather than kept, since it could hold key material thatDebugwould then print. - Generate
KeyPair Request POST /v2/keys/generate: a key pair whose private key stays on the server.- Generated
KeyPair - The answer of
POST /v2/keys/generate. - Hash
Request POST /v2/hash: the digest of the UTF-8 bytes ofdata.- Hash
Result - The answer of
POST /v2/hash. - Health
- The answer of
GET /health. - Hex
- Bytes the API carries as lowercase hex (
contentEncoding: base16): public keys, signatures, digests, MACs, KEM ciphertexts and HPKE output. Serialises as lowercase hex and reads either case. - Hpke
Keygen Request POST /v2/hpke/keygen: an HPKE key pair held by the server.- Hpke
Open Request POST /v2/hpke/open: opens with a server-held HPKE key.- Hpke
Opened - The answer of
POST /v2/hpke/open: the plaintext as UTF-8 text and as bytes. - Hpke
Seal Request POST /v2/hpke/seal: HPKE base or PSK mode to a public key.- Hpke
Sealed - The answer of
POST /v2/hpke/seal. - Http
Request - One request, as the client hands it to a
Transport. - Http
Response - One answer, of any status.
- Hybrid
Decapsulate Request POST /v2/pq/hybrid/decapsulate: the combined shared secret, with a server-held hybrid key.- Hybrid
Encapsulate Request POST /v2/pq/hybrid/encapsulate: X25519 and ML-KEM-768 to a hybrid public key.- Hybrid
Encapsulation - The answer of
POST /v2/pq/hybrid/encapsulate. - Hybrid
KeyPair - The answer of
POST /v2/pq/hybrid/keygen. - Inventory
Entry - One package of the cryptographic inventory.
- Iso20022
Envelope - A dual-signed ISO 20022 envelope, as crypto-lib writes it.
- Iso20022
Verification - The answer of
POST /v2/stream/iso20022. - Iso20022
Verify Request POST /v2/stream/iso20022: checks an envelope’s digest and both signatures againsttrusted_keys.- KdfParams
- Tuning of
POST /v2/kdf; each member applies to some algorithms only. - KdfRequest
POST /v2/kdf: derives a key from a password or input key material.- KdfResult
- The answer of
POST /v2/kdf. - KeyId
Request - A request naming one server-held key.
- KeyMetadata
- Metadata recorded with a generated key.
- KeyPair
- A server-held key pair: its identifier, algorithm and public key.
- KeyUnwrap
Request POST /v2/keys/unwrap: unwraps a key. The answer is the key itself.- KeyWrap
Request POST /v2/keys/wrap: wraps a key under a key-encryption key.- KeyWrap
Result - The answer of
POST /v2/keys/wrap. - KmsCiphertext
- The answer of
POST /v2/kms/encrypt. - KmsCreate
KeyRequest POST /v2/kms/create-key.- KmsData
Key - The answer of
POST /v2/kms/generate-data-key. - KmsDecrypt
Request POST /v2/kms/decrypt.- KmsEncrypt
Request POST /v2/kms/encrypt. Build it withKmsEncryptRequest::textorKmsEncryptRequest::bytes, which setencodingto match.- KmsGenerate
Data KeyRequest POST /v2/kms/generate-data-key.- KmsKey
- The answer of
POST /v2/kms/create-key. - KmsPlaintext
- The answer of
POST /v2/kms/decrypt: the plaintext as UTF-8 text and as bytes. - KmsUnwrap
Request POST /v2/kms/unwrap.- KmsUnwrapped
- The answer of
POST /v2/kms/unwrap. - KmsWrap
Request POST /v2/kms/wrap.- KmsWrapped
- The answer of
POST /v2/kms/wrap. - Liveness
- The answer of
GET /live. - MacRequest
POST /v2/hmac: the HMAC of the UTF-8 bytes ofdata.- MacResult
- The answer of
POST /v2/hmac. - MacVerify
Request POST /v2/hmac/verify: whethermacis the HMAC ofdata.- MlDsa
Keygen Request POST /v2/pq/dsa/keygen: an ML-DSA key pair held by the server.- MlDsa
Verify Request POST /v2/pq/dsa/verify: an ML-DSA signature against a public key.- MlKem
Decapsulate Request POST /v2/pq/decapsulate: the shared secret, with a server-held ML-KEM-768 key.- MlKem
Encapsulate Request POST /v2/pq/encapsulate: a shared secret for an ML-KEM-768 public key.- MlKem
Encapsulation - The answer of
POST /v2/pq/encapsulate. - Multi
PqCiphertext - The answer of
POST /v2/stream/multi-pq-encrypt. - Multi
PqPlaintext - The answer of
POST /v2/stream/multi-pq-decrypt. - Multi
Recipient Ciphertext - The answer of
POST /v2/multi-recipient/encrypt. - Multi
Recipient Encrypt Request POST /v2/multi-recipient/encrypt: one ciphertext, a wrapped key per recipient.- Opaque
Login Finish Request POST /v2/opaque/login/finish: verifies KE3. No credentials needed.- Opaque
Login Init Request POST /v2/opaque/login/init: evaluates KE1. No credentials needed.- Opaque
Login Init Result - The answer of
POST /v2/opaque/login/init. - Opaque
Register Finish Request POST /v2/opaque/register/finish: stores the registration record.- Opaque
Register Init Request POST /v2/opaque/register/init: evaluates a blinded registration request. Needs credentials whose subject iscredential_identifier.- Opaque
Register Init Result - The answer of
POST /v2/opaque/register/init. - Opaque
Registered - The answer of
POST /v2/opaque/register/finish. - Opaque
Session - The answer of
POST /v2/opaque/login/finish. - Password
Decrypt Request POST /v2/password/decrypt: opens a password envelope. The answer is the plaintext itself.- Password
Encrypt Request POST /v2/password/encrypt: Argon2id key derivation and XChaCha20-Poly1305.- Password
Encrypt Result - The answer of
POST /v2/password/encrypt. - Password
Hash Request POST /v2/password/hash: an Argon2id hash of a password.- Password
Hash Result - The answer of
POST /v2/password/hash. - Password
Verify Request POST /v2/password/verify: whetherpasswordmatches a stored hash.- Password
Verify Result - The answer of
POST /v2/password/verify. - Plaintext
- A decrypted plaintext, as UTF-8 text (invalid sequences become U+FFFD).
- Problem
- RFC 9457 problem details (
application/problem+json). - RawRequest
- A request for
Client::send_raw: any method and path, with an optional body and extra headers. - Readiness
- The answer of
GET /ready. A server that is not ready answers503, which arrives as anError::Api. - Readiness
Checks - The checks behind
GET /ready. - Recipient
- One recipient of
POST /v2/multi-recipient/encrypt. - Recipient
Share - One recipient’s share of a multi-recipient ciphertext.
- Recorded
KeyMetadata - The metadata the server recorded with a key;
kidis always set. - Reqwest
Transport - The default
Transport: one pooledreqwestclient per SDK client and its clones, with rustls (the platform’s trust store, verification always on), HTTP/2 by ALPN, gzip, keep-alive, and redirects refused. Responses are read up to 64 MiB. - Retry
Policy - When a
Clienttries a call again. - Sealed
- A sealed box and its algorithm.
- Sealedbox
Open Request POST /v2/sealedbox/openandopen-pq: opens a sealed box with a server-held key. The answer is the plaintext itself.- Sealedbox
Seal PqRequest POST /v2/sealedbox/seal-pq: a hybrid X25519 and ML-KEM-768 sealed box.- Sealedbox
Seal Request POST /v2/sealedbox/seal: an anonymous X25519 sealed box.- Secret
Bytes - Secret bytes the API carries as hex: private and secret keys, shared secrets, derived and unwrapped keys, data keys, symmetric keys sent to the server.
- Secret
String - Secret text: passwords, plaintexts and the decrypted text the server returns.
- Secretbox
Open Request POST /v2/secretbox/open: opens a secretbox. The answer is the plaintext itself.- Secretbox
Seal Request POST /v2/secretbox/seal: XChaCha20-Poly1305 with optional associated data.- Service
Info - The answer of
GET /: what the service is. - Shared
Secret - A shared secret from a decapsulation.
- Sign
Request POST /v2/sign(Ed25519) and the ML-DSA and SLH-DSA sign calls: signs the UTF-8 bytes ofmessagewith a server-held key.- Signature
- A signature and the algorithm that made it.
- SlhDsa
Keygen Request POST /v2/pq/slh-dsa/keygen: an SLH-DSA key pair held by the server.- SlhDsa
Verify Request POST /v2/pq/slh-dsa/verify: an SLH-DSA signature against a public key.- Stream
Multi PqDecrypt Request POST /v2/stream/multi-pq-decrypt: opens a multi-recipient stream with a server-held hybrid key.- Stream
Multi PqEncrypt Request POST /v2/stream/multi-pq-encrypt: a hybrid post-quantum stream for several recipients.- Stream
PqDecrypt Request POST /v2/stream/pq-decrypt: opens a stream with a server-held hybrid key.- Stream
PqEncrypt Request POST /v2/stream/pq-encrypt: chunked hybrid post-quantum encryption.- Stream
Recipient - One recipient of a multi-recipient stream.
- Stream
Sign Item - One message of a batch sign.
- Stream
Sign Request POST /v2/stream/sign: Ed25519 signatures over many messages.- Stream
Sign Result - The answer of
POST /v2/stream/sign. - Stream
Signature - One signature of a batch.
- Stream
Verification - One outcome of a batch verification.
- Stream
Verify Item - One signature to check in a batch.
- Stream
Verify Request POST /v2/stream/verify: checks many Ed25519 signatures.- Stream
Verify Result - The answer of
POST /v2/stream/verify. - Transport
Error - No answer arrived.
- Trusted
Keys - The signer’s public keys, as the caller trusts them.
- Validation
Error - One field that failed validation.
- Verification
- The answer of a verification: whether the signature or tag holds.
- Verify
Request POST /v2/verify: an Ed25519 signature against a public key.
Enums§
- Error
- What went wrong with a call. Every variant wraps a type of its own, so a caller can match the kind and keep the details.
- Hash
Algorithm - Hash algorithms of
POST /v2/hash. - Hpke
Aead - HPKE AEADs.
- Hpke
Data - An HPKE input (plaintext,
info,aad). - HpkeKem
- HPKE KEMs.
- KdfAlgorithm
- Key derivation functions of
POST /v2/kdf. - KeyAlgorithm
- Key pair algorithms of
POST /v2/keys/generate. - KeyUse
- What a key is for (JWK
use). - KeyWrap
Algorithm - AES key wrap modes.
- KmsEncoding
- How
POST /v2/kms/encryptreadsplaintext. Never guessed. - KmsKey
Usage - What a KMS key is for.
- MacAlgorithm
- HMAC hash functions of
POST /v2/hmacandPOST /v2/hmac/verify. - MlDsa
Level - ML-DSA security levels (FIPS 204).
- Opaque
Suite - OPAQUE cipher suites.
- Recipient
Type - What kind of key a multi-recipient recipient has.
- SlhDsa
Variant - SLH-DSA parameter sets (FIPS 205).
- Traceparent
- The W3C
traceparentheader the client sends.
Constants§
- DEFAULT_
TIMEOUT - The per-attempt timeout of a new client, until
ClientBuilder::timeoutchanges it. - USER_
AGENT - The
User-Agentevery request sends:crypto-service-sdk-rust/<VERSION>. - VERSION
- This crate’s version, from
Cargo.toml.
Traits§
- Transport
- Sends one HTTP request and reads the whole answer.
Type Aliases§
- BoxFuture
- A boxed, sendable future, as
Transport::sendreturns.