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