spiffe-rustls 0.5.0

SPIFFE-based mutual TLS integration for rustls
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108

//! # spiffe-rustls
//!
//! `spiffe-rustls` integrates [`rustls`] with SPIFFE/SPIRE using a live
//! [`spiffe::X509Source`] (SPIFFE Workload API).
//!
//! Provides builders for [`rustls::ClientConfig`] and
//! [`rustls::ServerConfig`] backed by an `X509Source`. When the SPIRE
//! agent rotates X.509 SVIDs or trust bundles, **new TLS handshakes automatically
//! use the updated material**, without restarting the application.
//!
//! Focuses on TLS authentication and **connection-level authorization
//! via SPIFFE IDs**, while delegating all cryptography and TLS mechanics to
//! `rustls`.
//!
//! When SPIFFE federation is configured, the crate automatically selects the correct
//! trust domain bundle based on the peer's SPIFFE ID. Authorization is applied **after**
//! cryptographic verification succeeds.
//!
//! For outbound TLS, peer identity is the SPIFFE ID in the URI SAN, not the TLS server name.
//! Connecting to `localhost` or an IP is supported even when the X.509-SVID has no matching DNS SAN.
//!
//! ## Feature flags
//!
//! Exactly **one** `rustls` crypto provider must be enabled:
//!
//! * `ring` (default)
//! * `aws-lc-rs`
//!
//! Enabling more than one provider results in a compile-time error.

#![expect(unused_crate_dependencies, reason = "used in the examples")]
#![expect(clippy::multiple_crate_versions, reason = "transitive")]

#[cfg(all(feature = "ring", feature = "aws-lc-rs"))]
compile_error!("Enable only one crypto provider feature: `ring` or `aws-lc-rs`.");

#[cfg(not(any(feature = "ring", feature = "aws-lc-rs")))]
compile_error!("Enable one crypto provider feature: `ring` (default) or `aws-lc-rs`.");

pub mod authorizer;

mod crypto;
mod error;
mod material;

mod observability;
mod prelude;

mod client;
mod policy;
mod resolve;
mod server;
mod verifier;

// Public re-exports
pub use authorizer::{any, exact, trust_domains, Authorizer};
pub use client::ClientConfigBuilder;
pub use error::{Error, Result};
pub use policy::TrustDomainPolicy;
pub use policy::TrustDomainPolicy::{AllowList, AnyInBundleSet, LocalOnly};
pub use server::ServerConfigBuilder;
pub use spiffe::{SpiffeId, TrustDomain};

/// Constructor for the mTLS client builder.
///
/// Creates a client builder with default settings (accepts any SPIFFE ID, uses all bundles from the Workload API).
///
/// # Examples
///
/// ```no_run
/// use spiffe_rustls::{authorizer, mtls_client};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let source = spiffe::X509Source::new().await?;
///
/// let client_config = mtls_client(source)
///     .authorize(authorizer::exact([
///         "spiffe://example.org/myservice",
///     ])?)
///     .build()?;
/// # Ok(())
/// # }
/// ```
pub fn mtls_client(source: spiffe::X509Source) -> ClientConfigBuilder {
    ClientConfigBuilder::new(source)
}

/// Constructor for the mTLS server builder.
///
/// Creates a server builder with default settings (accepts any SPIFFE ID, uses all bundles from the Workload API).
///
/// # Examples
///
/// ```no_run
/// use spiffe_rustls::{authorizer, mtls_server};
///
/// # async fn example() -> Result<(), Box<dyn std::error::Error>> {
/// let source = spiffe::X509Source::new().await?;
///
/// let server_config = mtls_server(source)
///     .authorize(authorizer::trust_domains(["example.org"])?)
///     .build()?;
/// # Ok(())
/// # }
/// ```
pub fn mtls_server(source: spiffe::X509Source) -> ServerConfigBuilder {
    ServerConfigBuilder::new(source)
}