crypto_service_sdk/lib.rs
1// SPDX-License-Identifier: Apache-2.0 OR MIT
2//! Typed async and blocking client for the Crypto Service REST API.
3//!
4//! [crypto-server](https://github.com/sebastienrousseau/crypto-service)
5//! exposes hashing, MACs, key derivation, AEAD, server-held signing and
6//! decryption keys, ML-KEM, ML-DSA, SLH-DSA, HPKE, KMS and OPAQUE over
7//! HTTP. This crate is a thin client for its v2 API: one method per
8//! operation, and no cryptography of its own. Every operation is an HTTP
9//! call to the server.
10//!
11//! ```no_run
12//! use crypto_service_sdk::{Client, HashAlgorithm, HashRequest};
13//!
14//! # async fn run() -> Result<(), crypto_service_sdk::Error> {
15//! let client = Client::builder("http://127.0.0.1:3000")
16//! .api_key("synthetic-api-key-0000000000000000")
17//! .build()?;
18//! let digest = client
19//! .hash(&HashRequest {
20//! algorithm: HashAlgorithm::Sha256,
21//! data: "abc".into(),
22//! })
23//! .await?;
24//! println!("{}", digest.digest);
25//! # Ok(())
26//! # }
27//! ```
28//!
29//! A non-2xx answer becomes [`Error::Api`] with the server's RFC 9457
30//! [`Problem`]; no answer at all becomes [`Error::Transport`]. Retries are
31//! off unless a [`RetryPolicy`] turns them on, and a call that creates or
32//! deletes server state is never retried after the server may have acted
33//! on it. Keys, passwords and plaintexts travel in [`SecretBytes`] and
34//! [`SecretString`], which are zeroised on drop and redacted in `Debug`.
35//!
36//! With the `blocking` feature, `blocking::Client` offers the same methods
37//! without `async`.
38#![forbid(unsafe_code)]
39#![warn(missing_docs)]
40
41mod builder;
42mod client;
43mod encoding;
44mod error;
45mod operations;
46mod retry;
47mod secret;
48mod transport;
49mod types;
50
51#[cfg(feature = "blocking")]
52pub mod blocking;
53
54#[cfg(test)]
55mod stub;
56
57/// The decoding paths without the network, for `fuzz/` and `benches/`.
58/// Not public API: it exists only under `cfg(fuzzing)`, with the
59/// `internals` feature, and in unit tests.
60#[cfg(any(fuzzing, test, feature = "internals"))]
61#[doc(hidden)]
62pub mod fuzzing;
63
64pub use builder::{ClientBuilder, Traceparent};
65pub use client::{Client, RawRequest, DEFAULT_TIMEOUT, USER_AGENT, VERSION};
66pub use encoding::{Base64, EncodingError, Hex};
67pub use error::{ApiError, DecodeError, Error, Problem, TransportError, ValidationError};
68pub use retry::RetryPolicy;
69pub use secret::{SecretBytes, SecretString};
70pub use transport::{BoxFuture, HttpRequest, HttpResponse, ReqwestTransport, Transport};
71pub use types::*;
72
73/// `http`, re-exported for [`RawRequest`], [`HttpRequest`] and custom
74/// [`Transport`]s.
75pub use http;
76
77/// Compiles the README's Rust snippets as doctests.
78#[cfg(doctest)]
79#[doc = include_str!("../README.md")]
80struct ReadmeDoctests;