spiffe_rustls/lib.rs
1#![deny(missing_docs)]
2#![deny(unsafe_code)]
3#![warn(missing_debug_implementations)]
4#![warn(clippy::all)]
5#![warn(clippy::pedantic)]
6#![allow(clippy::module_name_repetitions)]
7#![allow(clippy::must_use_candidate)]
8
9//! # spiffe-rustls
10//!
11//! `spiffe-rustls` integrates [`rustls`] with SPIFFE/SPIRE using a live
12//! [`spiffe::X509Source`] (SPIFFE Workload API).
13//!
14//! It provides builders for [`rustls::ClientConfig`] and
15//! [`rustls::ServerConfig`] that are backed by an `X509Source`. When the SPIRE
16//! agent rotates X.509 SVIDs or trust bundles, **new TLS handshakes automatically
17//! use the updated material**, without restarting the application.
18//!
19//! The crate focuses on TLS authentication and **connection-level authorization
20//! via SPIFFE IDs**, while delegating all cryptography and TLS mechanics to
21//! `rustls`.
22//!
23//! ## Quick example (client)
24//!
25//! ```no_run
26//! use spiffe_rustls::{ClientConfigBuilder, ClientConfigOptions};
27//! use std::sync::Arc;
28//!
29//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
30//! let source = spiffe::X509Source::new().await?;
31//!
32//! let opts = ClientConfigOptions {
33//! trust_domain: "example.org".try_into()?,
34//! authorize_server: Arc::new(|id: &str| {
35//! id == "spiffe://example.org/myservice"
36//! }),
37//! };
38//!
39//! let client_config = ClientConfigBuilder::new(source, opts).build()?;
40//! # Ok(())
41//! # }
42//! ```
43//!
44//! The resulting `ClientConfig` can be used directly with `rustls` or integrated
45//! into higher-level libraries such as `tokio-rustls` or `tonic-rustls`.
46//!
47//! ## Feature flags
48//!
49//! Exactly **one** `rustls` crypto provider must be enabled:
50//!
51//! * `ring` (default)
52//! * `aws-lc-rs`
53//!
54//! Enabling more than one provider results in a compile-time error.
55
56#[cfg(all(feature = "ring", feature = "aws-lc-rs"))]
57compile_error!("Enable only one crypto provider feature: `ring` or `aws-lc-rs`.");
58
59#[cfg(not(any(feature = "ring", feature = "aws-lc-rs")))]
60compile_error!("Enable one crypto provider feature: `ring` (default) or `aws-lc-rs`.");
61
62mod crypto;
63
64mod client;
65mod error;
66mod material;
67mod resolve;
68mod server;
69mod types;
70mod verifier;
71
72pub use client::{ClientConfigBuilder, ClientConfigOptions};
73pub use error::{Error, Result};
74pub use server::{ServerConfigBuilder, ServerConfigOptions};
75pub use types::{authorize_any, authorize_exact, AuthorizeSpiffeId};