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//! Provides builders for [`rustls::ClientConfig`] and
7//! [`rustls::ServerConfig`] 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//! Focuses on TLS authentication and **connection-level authorization
12//! via SPIFFE IDs**, while delegating all cryptography and TLS mechanics to
13//! `rustls`.
14//!
15//! When SPIFFE federation is configured, the crate automatically selects the correct
16//! trust domain bundle based on the peer's SPIFFE ID. Authorization is applied **after**
17//! cryptographic verification succeeds.
18//!
19//! ## Feature flags
20//!
21//! Exactly **one** `rustls` crypto provider must be enabled:
22//!
23//! * `ring` (default)
24//! * `aws-lc-rs`
25//!
26//! Enabling more than one provider results in a compile-time error.
27
28#![expect(unused_crate_dependencies, reason = "used in the examples")]
29#![expect(clippy::multiple_crate_versions, reason = "transitive")]
30
31#[cfg(all(feature = "ring", feature = "aws-lc-rs"))]
32compile_error!("Enable only one crypto provider feature: `ring` or `aws-lc-rs`.");
33
34#[cfg(not(any(feature = "ring", feature = "aws-lc-rs")))]
35compile_error!("Enable one crypto provider feature: `ring` (default) or `aws-lc-rs`.");
36
37pub mod authorizer;
38
39mod crypto;
40mod error;
41mod material;
42
43mod observability;
44mod prelude;
45
46mod client;
47mod policy;
48mod resolve;
49mod server;
50mod verifier;
51
52// Public re-exports
53pub use authorizer::{any, exact, trust_domains, Authorizer};
54pub use client::ClientConfigBuilder;
55pub use error::{Error, Result};
56pub use policy::TrustDomainPolicy;
57pub use policy::TrustDomainPolicy::{AllowList, AnyInBundleSet, LocalOnly};
58pub use server::ServerConfigBuilder;
59pub use spiffe::{SpiffeId, TrustDomain};
60
61/// Constructor for the mTLS client builder.
62///
63/// Creates a client builder with default settings (accepts any SPIFFE ID, uses all bundles from the Workload API).
64///
65/// # Examples
66///
67/// ```no_run
68/// use spiffe_rustls::{authorizer, mtls_client};
69///
70/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
71/// let source = spiffe::X509Source::new().await?;
72///
73/// let client_config = mtls_client(source)
74///     .authorize(authorizer::exact([
75///         "spiffe://example.org/myservice",
76///     ])?)
77///     .build()?;
78/// # Ok(())
79/// # }
80/// ```
81pub fn mtls_client(source: spiffe::X509Source) -> ClientConfigBuilder {
82    ClientConfigBuilder::new(source)
83}
84
85/// Constructor for the mTLS server builder.
86///
87/// Creates a server builder with default settings (accepts any SPIFFE ID, uses all bundles from the Workload API).
88///
89/// # Examples
90///
91/// ```no_run
92/// use spiffe_rustls::{authorizer, mtls_server};
93///
94/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
95/// let source = spiffe::X509Source::new().await?;
96///
97/// let server_config = mtls_server(source)
98///     .authorize(authorizer::trust_domains(["example.org"])?)
99///     .build()?;
100/// # Ok(())
101/// # }
102/// ```
103pub fn mtls_server(source: spiffe::X509Source) -> ServerConfigBuilder {
104    ServerConfigBuilder::new(source)
105}
spiffe_rustls/lib.rs

spiffe_rustls/
lib.rs
