Prepare release spiffe-rustls 0.1.3 (#207)

Signed-off-by: Max Lambrecht <[email protected]>

Author: maxlambrecht

spiffe-rustls/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## [0.1.3] – 2025-12-24
+
+* Documentation improvements only. No functional changes.
+
+
 ## [0.1.2] – 2025-12-24
 
 * Migrated to the Rust 2021 edition.

spiffe-rustls/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spiffe-rustls"
-version = "0.1.2"
+version = "0.1.3"
 edition = "2021"
 rust-version = "1.83"
 license = "Apache-2.0"

spiffe-rustls/README.md

@@ -16,46 +16,57 @@ delegating all cryptography and TLS mechanics to `rustls`.
 
 ---
 
-## Features
+## Quick start
 
-`spiffe-rustls` supports multiple `rustls` crypto providers:
+### 1. Create an X509Source
 
-```toml
-[features]
-default = ["ring"]
-ring = ["rustls/ring"]
-aws-lc-rs = ["rustls/aws_lc_rs"]
+The source is configured via `SPIFFE_ENDPOINT_SOCKET`:
+
+```rust
+let source = spiffe::X509Source::new().await?;
 ````
 
-* **Default:** `ring`
-* **Optional:** `aws-lc-rs`
+---
 
-Exactly **one** provider must be enabled. Enabling more than one results in a compile-time error.
+### 2. Build a rustls client configuration
 
-Example (AWS-LC):
+```rust
+use spiffe_rustls::{ClientConfigBuilder, ClientConfigOptions};
+use std::sync::Arc;
 
-```bash
-cargo add spiffe-rustls --no-default-features --features aws-lc-rs
+let opts = ClientConfigOptions {
+    trust_domain: "example.org".try_into()?,
+    // Authorize the server by its SPIFFE ID (connection-level authorization)
+    authorize_server: Arc::new(|id: &str| {
+        id == "spiffe://example.org/myservice"
+    }),
+};
+
+let client_cfg = ClientConfigBuilder::new(source.clone(), opts)
+    .build()
+    .await?;
 ```
 
-Provider choice affects only cryptographic primitives; **SPIFFE semantics and API behavior are
-identical** across providers.
+The resulting `ClientConfig` can be used directly with `rustls`, or integrated into
+`tokio-rustls`, `tonic-rustls`, or similar libraries.
 
 ---
 
-## Public API
+## API overview
 
-The public API is intentionally small:
+The public API is intentionally small and consists of two builders:
 
-* `ClientConfigBuilder`, `ClientConfigOptions`
-* `ServerConfigBuilder`, `ServerConfigOptions`
+* `ClientConfigBuilder`
+* `ServerConfigBuilder`
 
-Both builders retain an `Arc<X509Source>` and always use the **latest SVIDs and bundles** for new TLS
-handshakes.
+Each builder:
 
----
+* retains an `Arc<X509Source>`
+* builds a `rustls::{ClientConfig, ServerConfig}`
+* always uses the **latest SVIDs and trust bundles**
+* authorizes peers by SPIFFE ID (URI SAN)
 
-## Builders
+---
 
 ### ClientConfigBuilder
 
@@ -65,6 +76,8 @@ Builds a `rustls::ClientConfig` that:
 * validates the server certificate chain against the trust domain bundle
 * authorizes the server by SPIFFE ID (URI SAN)
 
+---
+
 ### ServerConfigBuilder
 
 Builds a `rustls::ServerConfig` that:
@@ -111,38 +124,30 @@ authentication.
 
 ---
 
-## Quick start
-
-### 1. Create an X509Source
+## Features
 
-The source is configured via `SPIFFE_ENDPOINT_SOCKET`:
+`spiffe-rustls` supports multiple `rustls` crypto providers:
 
-```rust
-let source = spiffe::X509Source::new().await?;
+```toml
+[features]
+default = ["ring"]
+ring = ["rustls/ring"]
+aws-lc-rs = ["rustls/aws_lc_rs"]
 ```
 
----
-
-### 2. Build a rustls client configuration
+* **Default:** `ring`
+* **Optional:** `aws-lc-rs`
 
-```rust
-use spiffe_rustls::{ClientConfigBuilder, ClientConfigOptions};
-use std::sync::Arc;
+Exactly **one** provider must be enabled. Enabling more than one results in a compile-time error.
 
-let opts = ClientConfigOptions {
-    trust_domain: "example.org".try_into()?,
-    authorize_server: Arc::new(|id: &str| {
-        id == "spiffe://example.org/myservice"
-    }),
-};
+Example (AWS-LC):
 
-let client_cfg = ClientConfigBuilder::new(source.clone(), opts)
-    .build()
-    .await?;
+```bash
+cargo add spiffe-rustls --no-default-features --features aws-lc-rs
 ```
 
-The resulting `ClientConfig` can be used directly with `rustls`, or integrated into
-`tokio-rustls`, `tonic-rustls`, or similar libraries.
+Provider choice affects only cryptographic primitives; **SPIFFE semantics and API behavior are
+identical** across providers.
 
 ---
 

spiffe-rustls/src/client.rs

@@ -7,22 +7,26 @@ use rustls::ClientConfig;
 use spiffe::{TrustDomain, X509Source};
 use std::sync::Arc;
 
-/// Options for building a SPIFFE-aware `rustls::ClientConfig`.
+/// Configuration options for [`ClientConfigBuilder`].
+///
+/// These options control trust bundle selection and server authorization.
 #[derive(Clone)]
 pub struct ClientConfigOptions {
     /// Trust domain whose bundle is used as the verification root set.
     pub trust_domain: TrustDomain,
 
     /// Authorization hook invoked with the server SPIFFE ID.
     ///
-    /// Returning `false` rejects the peer even if the certificate chain is valid.
+    /// The hook receives the SPIFFE ID extracted from the server certificate’s
+    /// URI SAN and must return `true` to allow the connection.
     pub authorize_server: AuthorizeSpiffeId,
 }
 
 impl ClientConfigOptions {
-    /// Creates options that accept any server SPIFFE ID for the given trust domain.
+    /// Creates options that authenticate the server but allow any SPIFFE ID.
     ///
-    /// Authentication still happens via bundle verification; only authorization is permissive.
+    /// This disables authorization while retaining full TLS authentication.
+    /// Use only if authorization is performed at another layer.
     pub fn allow_any(trust_domain: TrustDomain) -> Self {
         Self {
             trust_domain,
@@ -31,14 +35,26 @@ impl ClientConfigOptions {
     }
 }
 
-/// Builds a `rustls::ClientConfig` backed by an [`spiffe::X509Source`].
+/// Builds a [`rustls::ClientConfig`] backed by a live SPIFFE `X509Source`.
+///
+/// The resulting client configuration:
+///
+/// * presents the current SPIFFE X.509 SVID as the client certificate
+/// * validates the server certificate chain against the trust domain bundle
+/// * authorizes the server by SPIFFE ID (URI SAN)
+///
+/// The builder retains an `Arc<X509Source>`. When the underlying SVID or trust
+/// bundle is rotated by the SPIRE agent, **new TLS handshakes automatically use
+/// the updated material**.
+///
+/// ## Authorization
 ///
-/// The resulting config:
-/// - presents the current SVID as the client certificate
-/// - verifies server certificates using the trust domain bundle
-/// - authorizes the server by SPIFFE ID (URI SAN)
+/// Server authorization is performed by invoking the provided
+/// [`AuthorizeSpiffeId`] hook with the server’s SPIFFE ID extracted from the
+/// certificate’s URI SAN.
 ///
-/// New handshakes use the latest SVID/bundle material after rotations.
+/// Use [`ClientConfigOptions::allow_any`] to disable authorization while
+/// retaining full TLS authentication.
 pub struct ClientConfigBuilder {
     source: Arc<X509Source>,
     opts: ClientConfigOptions,

spiffe-rustls/src/lib.rs

@@ -1,14 +1,51 @@
-//! rustls integration for SPIFFE `X509Source` (SPIRE Workload API).
+//! # spiffe-rustls
 //!
-//! This crate builds `rustls::ClientConfig` and `rustls::ServerConfig` that use an always-up-to-date
-//! [`spiffe::X509Source`] for:
-//! - the local X.509 SVID (certificate + private key)
-//! - the trust bundle for peer verification (by trust domain)
+//! `spiffe-rustls` integrates [`rustls`] with SPIFFE/SPIRE using a live
+//! [`spiffe::X509Source`] (SPIFFE Workload API).
 //!
-//! Peer authorization is performed using a user-provided callback over the peer SPIFFE ID
-//! (URI SAN, e.g. `spiffe://example.org/myservice`).
+//! It provides builders for [`rustls::ClientConfig`] and
+//! [`rustls::ServerConfig`] that are 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.
 //!
-//! See `examples/mtls_tcp_client` and `examples/mtls_tcp_server` for complete runnable examples.
+//! The crate focuses on TLS authentication and **connection-level authorization
+//! via SPIFFE IDs**, while delegating all cryptography and TLS mechanics to
+//! `rustls`.
+//!
+//! ## Quick example (client)
+//!
+//! ```no_run
+//! use spiffe_rustls::{ClientConfigBuilder, ClientConfigOptions};
+//! use std::sync::Arc;
+//!
+//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
+//! let source = spiffe::X509Source::new().await?;
+//!
+//! let opts = ClientConfigOptions {
+//!     trust_domain: "example.org".try_into()?,
+//!     authorize_server: Arc::new(|id: &str| {
+//!         id == "spiffe://example.org/myservice"
+//!     }),
+//! };
+//!
+//! let client_config = ClientConfigBuilder::new(source, opts)
+//!     .build()
+//!     .await?;
+//! # Ok(())
+//! # }
+//! ```
+//!
+//! The resulting `ClientConfig` can be used directly with `rustls` or integrated
+//! into higher-level libraries such as `tokio-rustls` or `tonic-rustls`.
+//!
+//! ## 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.
 
 #[cfg(all(feature = "ring", feature = "aws-lc-rs"))]
 compile_error!("Enable only one crypto provider feature: `ring` or `aws-lc-rs`.");

spiffe-rustls/src/server.rs

@@ -7,22 +7,26 @@ use rustls::ServerConfig;
 use spiffe::{TrustDomain, X509Source};
 use std::sync::Arc;
 
-/// Options for building a SPIFFE-aware `rustls::ServerConfig`.
+/// Configuration options for [`ServerConfigBuilder`].
+///
+/// These options control trust bundle selection and client authorization.
 #[derive(Clone)]
 pub struct ServerConfigOptions {
     /// Trust domain whose bundle is used as the verification root set.
     pub trust_domain: TrustDomain,
 
     /// Authorization hook invoked with the client SPIFFE ID.
     ///
-    /// Returning `false` rejects the peer even if the certificate chain is valid.
+    /// The hook receives the SPIFFE ID extracted from the client certificate’s
+    /// URI SAN and must return `true` to allow the connection.
     pub authorize_client: AuthorizeSpiffeId,
 }
 
 impl ServerConfigOptions {
-    /// Creates options that accept any client SPIFFE ID for the given trust domain.
+    /// Creates options that authenticate clients but allow any SPIFFE ID.
     ///
-    /// Authentication still happens via bundle verification; only authorization is permissive.
+    /// This disables authorization while retaining full TLS authentication.
+    /// Use only if authorization is performed at another layer.
     pub fn allow_any(trust_domain: TrustDomain) -> Self {
         Self {
             trust_domain,
@@ -31,14 +35,26 @@ impl ServerConfigOptions {
     }
 }
 
-/// Builds a `rustls::ServerConfig` backed by an [`spiffe::X509Source`].
+/// Builds a [`rustls::ServerConfig`] backed by a live SPIFFE `X509Source`.
+///
+/// The resulting server configuration:
+///
+/// * presents the current SPIFFE X.509 SVID as the server certificate
+/// * requires and validates client certificates (mTLS)
+/// * authorizes the client by SPIFFE ID (URI SAN)
+///
+/// The builder retains an `Arc<X509Source>`. When the underlying SVID or trust
+/// bundle is rotated by the SPIRE agent, **new TLS handshakes automatically use
+/// the updated material**.
+///
+/// ## Authorization
 ///
-/// The resulting config:
-/// - presents the current SVID as the server certificate
-/// - requires and verifies client certificates (mTLS) using the trust domain bundle
-/// - authorizes the client by SPIFFE ID (URI SAN)
+/// Client authorization is performed by invoking the provided
+/// [`AuthorizeSpiffeId`] hook with the client’s SPIFFE ID extracted from the
+/// certificate’s URI SAN.
 ///
-/// New handshakes use the latest SVID/bundle material after rotations.
+/// Use [`ServerConfigOptions::allow_any`] to disable authorization while
+/// retaining full TLS authentication.
 pub struct ServerConfigBuilder {
     source: Arc<X509Source>,
     opts: ServerConfigOptions,