Skip to main content

Crate crypto_service_sdk

Crate crypto_service_sdk 

Source
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 blocking feature).

Structs§

Algorithms
The answer of GET /v2/algorithms: algorithm names by category.
ApiError
A non-2xx answer, with its RFC 9457 problem.
Argon2Params
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 in data. Informational input for CRA and DORA work.
CbomComponent
One component of the CBOM.
CbomProperty
A name and value pair of a CBOM component.
Ciphertext
A ciphertext and its algorithm.
Client
A client for one crypto-server.
ClientBuilder
Options for a Client; start with Client::builder.
DecodeError
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.
DecryptRequest
POST /v2/decrypt: opens what EncryptRequest produced.
DeletedKey
The answer of POST /v2/keys/delete.
DeprecationEntry
One algorithm and its suggested sunset.
DoraCompliance
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 {}.
EncodingError
A string that is not valid hex or base64.
EncryptRequest
POST /v2/encrypt: XChaCha20-Poly1305 under a caller-held key.
EnvelopeSignature
One signature of an ISO 20022 envelope.
ExportedKey
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 that Debug would then print.
GenerateKeyPairRequest
POST /v2/keys/generate: a key pair whose private key stays on the server.
GeneratedKeyPair
The answer of POST /v2/keys/generate.
HashRequest
POST /v2/hash: the digest of the UTF-8 bytes of data.
HashResult
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.
HpkeKeygenRequest
POST /v2/hpke/keygen: an HPKE key pair held by the server.
HpkeOpenRequest
POST /v2/hpke/open: opens with a server-held HPKE key.
HpkeOpened
The answer of POST /v2/hpke/open: the plaintext as UTF-8 text and as bytes.
HpkeSealRequest
POST /v2/hpke/seal: HPKE base or PSK mode to a public key.
HpkeSealed
The answer of POST /v2/hpke/seal.
HttpRequest
One request, as the client hands it to a Transport.
HttpResponse
One answer, of any status.
HybridDecapsulateRequest
POST /v2/pq/hybrid/decapsulate: the combined shared secret, with a server-held hybrid key.
HybridEncapsulateRequest
POST /v2/pq/hybrid/encapsulate: X25519 and ML-KEM-768 to a hybrid public key.
HybridEncapsulation
The answer of POST /v2/pq/hybrid/encapsulate.
HybridKeyPair
The answer of POST /v2/pq/hybrid/keygen.
InventoryEntry
One package of the cryptographic inventory.
Iso20022Envelope
A dual-signed ISO 20022 envelope, as crypto-lib writes it.
Iso20022Verification
The answer of POST /v2/stream/iso20022.
Iso20022VerifyRequest
POST /v2/stream/iso20022: checks an envelope’s digest and both signatures against trusted_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.
KeyIdRequest
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.
KeyUnwrapRequest
POST /v2/keys/unwrap: unwraps a key. The answer is the key itself.
KeyWrapRequest
POST /v2/keys/wrap: wraps a key under a key-encryption key.
KeyWrapResult
The answer of POST /v2/keys/wrap.
KmsCiphertext
The answer of POST /v2/kms/encrypt.
KmsCreateKeyRequest
POST /v2/kms/create-key.
KmsDataKey
The answer of POST /v2/kms/generate-data-key.
KmsDecryptRequest
POST /v2/kms/decrypt.
KmsEncryptRequest
POST /v2/kms/encrypt. Build it with KmsEncryptRequest::text or KmsEncryptRequest::bytes, which set encoding to match.
KmsGenerateDataKeyRequest
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.
KmsUnwrapRequest
POST /v2/kms/unwrap.
KmsUnwrapped
The answer of POST /v2/kms/unwrap.
KmsWrapRequest
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 of data.
MacResult
The answer of POST /v2/hmac.
MacVerifyRequest
POST /v2/hmac/verify: whether mac is the HMAC of data.
MlDsaKeygenRequest
POST /v2/pq/dsa/keygen: an ML-DSA key pair held by the server.
MlDsaVerifyRequest
POST /v2/pq/dsa/verify: an ML-DSA signature against a public key.
MlKemDecapsulateRequest
POST /v2/pq/decapsulate: the shared secret, with a server-held ML-KEM-768 key.
MlKemEncapsulateRequest
POST /v2/pq/encapsulate: a shared secret for an ML-KEM-768 public key.
MlKemEncapsulation
The answer of POST /v2/pq/encapsulate.
MultiPqCiphertext
The answer of POST /v2/stream/multi-pq-encrypt.
MultiPqPlaintext
The answer of POST /v2/stream/multi-pq-decrypt.
MultiRecipientCiphertext
The answer of POST /v2/multi-recipient/encrypt.
MultiRecipientEncryptRequest
POST /v2/multi-recipient/encrypt: one ciphertext, a wrapped key per recipient.
OpaqueLoginFinishRequest
POST /v2/opaque/login/finish: verifies KE3. No credentials needed.
OpaqueLoginInitRequest
POST /v2/opaque/login/init: evaluates KE1. No credentials needed.
OpaqueLoginInitResult
The answer of POST /v2/opaque/login/init.
OpaqueRegisterFinishRequest
POST /v2/opaque/register/finish: stores the registration record.
OpaqueRegisterInitRequest
POST /v2/opaque/register/init: evaluates a blinded registration request. Needs credentials whose subject is credential_identifier.
OpaqueRegisterInitResult
The answer of POST /v2/opaque/register/init.
OpaqueRegistered
The answer of POST /v2/opaque/register/finish.
OpaqueSession
The answer of POST /v2/opaque/login/finish.
PasswordDecryptRequest
POST /v2/password/decrypt: opens a password envelope. The answer is the plaintext itself.
PasswordEncryptRequest
POST /v2/password/encrypt: Argon2id key derivation and XChaCha20-Poly1305.
PasswordEncryptResult
The answer of POST /v2/password/encrypt.
PasswordHashRequest
POST /v2/password/hash: an Argon2id hash of a password.
PasswordHashResult
The answer of POST /v2/password/hash.
PasswordVerifyRequest
POST /v2/password/verify: whether password matches a stored hash.
PasswordVerifyResult
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 answers 503, which arrives as an Error::Api.
ReadinessChecks
The checks behind GET /ready.
Recipient
One recipient of POST /v2/multi-recipient/encrypt.
RecipientShare
One recipient’s share of a multi-recipient ciphertext.
RecordedKeyMetadata
The metadata the server recorded with a key; kid is always set.
ReqwestTransport
The default Transport: one pooled reqwest client 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.
RetryPolicy
When a Client tries a call again.
Sealed
A sealed box and its algorithm.
SealedboxOpenRequest
POST /v2/sealedbox/open and open-pq: opens a sealed box with a server-held key. The answer is the plaintext itself.
SealedboxSealPqRequest
POST /v2/sealedbox/seal-pq: a hybrid X25519 and ML-KEM-768 sealed box.
SealedboxSealRequest
POST /v2/sealedbox/seal: an anonymous X25519 sealed box.
SecretBytes
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.
SecretString
Secret text: passwords, plaintexts and the decrypted text the server returns.
SecretboxOpenRequest
POST /v2/secretbox/open: opens a secretbox. The answer is the plaintext itself.
SecretboxSealRequest
POST /v2/secretbox/seal: XChaCha20-Poly1305 with optional associated data.
ServiceInfo
The answer of GET /: what the service is.
SharedSecret
A shared secret from a decapsulation.
SignRequest
POST /v2/sign (Ed25519) and the ML-DSA and SLH-DSA sign calls: signs the UTF-8 bytes of message with a server-held key.
Signature
A signature and the algorithm that made it.
SlhDsaKeygenRequest
POST /v2/pq/slh-dsa/keygen: an SLH-DSA key pair held by the server.
SlhDsaVerifyRequest
POST /v2/pq/slh-dsa/verify: an SLH-DSA signature against a public key.
StreamMultiPqDecryptRequest
POST /v2/stream/multi-pq-decrypt: opens a multi-recipient stream with a server-held hybrid key.
StreamMultiPqEncryptRequest
POST /v2/stream/multi-pq-encrypt: a hybrid post-quantum stream for several recipients.
StreamPqDecryptRequest
POST /v2/stream/pq-decrypt: opens a stream with a server-held hybrid key.
StreamPqEncryptRequest
POST /v2/stream/pq-encrypt: chunked hybrid post-quantum encryption.
StreamRecipient
One recipient of a multi-recipient stream.
StreamSignItem
One message of a batch sign.
StreamSignRequest
POST /v2/stream/sign: Ed25519 signatures over many messages.
StreamSignResult
The answer of POST /v2/stream/sign.
StreamSignature
One signature of a batch.
StreamVerification
One outcome of a batch verification.
StreamVerifyItem
One signature to check in a batch.
StreamVerifyRequest
POST /v2/stream/verify: checks many Ed25519 signatures.
StreamVerifyResult
The answer of POST /v2/stream/verify.
TransportError
No answer arrived.
TrustedKeys
The signer’s public keys, as the caller trusts them.
ValidationError
One field that failed validation.
Verification
The answer of a verification: whether the signature or tag holds.
VerifyRequest
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.
HashAlgorithm
Hash algorithms of POST /v2/hash.
HpkeAead
HPKE AEADs.
HpkeData
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).
KeyWrapAlgorithm
AES key wrap modes.
KmsEncoding
How POST /v2/kms/encrypt reads plaintext. Never guessed.
KmsKeyUsage
What a KMS key is for.
MacAlgorithm
HMAC hash functions of POST /v2/hmac and POST /v2/hmac/verify.
MlDsaLevel
ML-DSA security levels (FIPS 204).
OpaqueSuite
OPAQUE cipher suites.
RecipientType
What kind of key a multi-recipient recipient has.
SlhDsaVariant
SLH-DSA parameter sets (FIPS 205).
Traceparent
The W3C traceparent header the client sends.

Constants§

DEFAULT_TIMEOUT
The per-attempt timeout of a new client, until ClientBuilder::timeout changes it.
USER_AGENT
The User-Agent every 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::send returns.