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//! By default, builders use [`TrustDomainPolicy::AnyInBundleSet`] and
20//! [`authorizer::any`]. This accepts any authenticated SPIFFE ID from any trust domain
21//! present in the source bundle set. For non-federated deployments, use
22//! [`TrustDomainPolicy::LocalOnly`]; for production deployments, configure an
23//! authorizer that matches the peer identities your application expects.
24//!
25//! For outbound TLS, peer identity is the SPIFFE ID in the URI SAN, not the TLS server name.
26//! Connecting to `localhost` or an IP is supported even when the X.509-SVID has no matching DNS SAN.
27//!
28//! ## Feature flags
29//!
30//! Exactly **one** `rustls` crypto provider must be enabled:
31//!
32//! * `ring` (default)
33//! * `aws-lc-rs`
34//!
35//! Enabling more than one provider results in a compile-time error.
36
37#![expect(unused_crate_dependencies, reason = "used in the examples")]
38#![expect(clippy::multiple_crate_versions, reason = "transitive")]
39
40#[cfg(all(feature = "ring", feature = "aws-lc-rs"))]
41compile_error!("Enable only one crypto provider feature: `ring` or `aws-lc-rs`.");
42
43#[cfg(not(any(feature = "ring", feature = "aws-lc-rs")))]
44compile_error!("Enable one crypto provider feature: `ring` (default) or `aws-lc-rs`.");
45
46pub mod authorizer;
47
48mod crypto;
49mod error;
50mod material;
51
52mod observability;
53mod prelude;
54
55mod client;
56mod policy;
57mod resolve;
58mod server;
59mod verifier;
60
61// Public re-exports
62pub use authorizer::{any, exact, trust_domains, Authorizer};
63pub use client::ClientConfigBuilder;
64pub use error::{Error, Result};
65pub use policy::TrustDomainPolicy;
66pub use policy::TrustDomainPolicy::{AllowList, AnyInBundleSet, LocalOnly};
67pub use server::ServerConfigBuilder;
68pub use spiffe::{SpiffeId, TrustDomain};
69
70/// Constructor for the mTLS client builder.
71///
72/// Creates a client builder with default settings:
73///
74/// * authorizer: [`authorizer::any`], which accepts any authenticated SPIFFE ID
75///   from any trust domain accepted by the configured trust-domain policy. By default,
76///   this means every trust domain in the source bundle set.
77/// * trust-domain policy: [`TrustDomainPolicy::AnyInBundleSet`], which accepts any
78///   trust domain present in the source bundle set
79///
80/// Production deployments should usually configure a more specific authorizer. Non-federated
81/// deployments should usually configure [`TrustDomainPolicy::LocalOnly`].
82///
83/// # Examples
84///
85/// ```no_run
86/// use spiffe_rustls::{authorizer, mtls_client};
87///
88/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
89/// let source = spiffe::X509Source::new().await?;
90///
91/// let client_config = mtls_client(source)
92///     .authorize(authorizer::exact([
93///         "spiffe://example.org/myservice",
94///     ])?)
95///     .build()?;
96/// # Ok(())
97/// # }
98/// ```
99pub fn mtls_client(source: spiffe::X509Source) -> ClientConfigBuilder {
100    ClientConfigBuilder::new(source)
101}
102
103/// Constructor for the mTLS server builder.
104///
105/// Creates a server builder with default settings:
106///
107/// * authorizer: [`authorizer::any`], which accepts any authenticated SPIFFE ID
108///   from any trust domain accepted by the configured trust-domain policy. By default,
109///   this means every trust domain in the source bundle set.
110/// * trust-domain policy: [`TrustDomainPolicy::AnyInBundleSet`], which accepts any
111///   trust domain present in the source bundle set
112///
113/// Production deployments should usually configure a more specific authorizer. Non-federated
114/// deployments should usually configure [`TrustDomainPolicy::LocalOnly`].
115///
116/// # Examples
117///
118/// ```no_run
119/// use spiffe_rustls::{authorizer, mtls_server};
120///
121/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
122/// let source = spiffe::X509Source::new().await?;
123///
124/// let server_config = mtls_server(source)
125///     .authorize(authorizer::trust_domains(["example.org"])?)
126///     .build()?;
127/// # Ok(())
128/// # }
129/// ```
130pub fn mtls_server(source: spiffe::X509Source) -> ServerConfigBuilder {
131    ServerConfigBuilder::new(source)
132}
spiffe_rustls/lib.rs

spiffe_rustls/
lib.rs
