Struct ClientConfigBuilder 

pub struct ClientConfigBuilder { /* private fields */ }

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 trust bundles from the Workload API
• 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.

Trust Domain Selection

The builder uses the bundle set from X509Source, which may contain bundles for multiple trust domains (when SPIFFE federation is configured). The verifier automatically selects the correct bundle based on the peer’s SPIFFE ID—no manual configuration is required. You can optionally restrict which trust domains are accepted using Self::trust_domain_policy.

The default policy is TrustDomainPolicy::AnyInBundleSet, which accepts any trust domain present in the source bundle set. For non-federated deployments, prefer TrustDomainPolicy::LocalOnly to restrict verification to the local trust domain.

Authorization

Server authorization is performed by invoking the provided Authorizer with the server’s SPIFFE ID extracted from the certificate’s URI SAN.

The default authorizer is crate::authorizer::any. It accepts any authenticated SPIFFE ID from any trust domain accepted by the configured trust-domain policy. By default, this means every trust domain in the source bundle set. Production deployments should usually configure a more specific authorizer.

Examples

use spiffe_rustls::{authorizer, mtls_client, AllowList};
use std::collections::BTreeSet;

let source = spiffe::X509Source::new().await?;

// Pass string literals directly - exact() and trust_domains() will convert them
let allowed_server_ids = [
    "spiffe://example.org/myservice",
    "spiffe://example.org/myservice2",
];

let mut allowed_trust_domains = BTreeSet::new();
allowed_trust_domains.insert("example.org".try_into()?);

let client_config = mtls_client(source)
    .authorize(authorizer::exact(allowed_server_ids)?)
    .trust_domain_policy(AllowList(allowed_trust_domains))
    .build()?;

Implementations

impl ClientConfigBuilder

pub fn new(source: X509Source) -> Self

Creates a new builder from an X509Source.

Defaults:

• Authorization: crate::authorizer::any, which accepts any authenticated SPIFFE ID from any trust domain accepted by the configured trust-domain policy. By default, this means every trust domain in the source bundle set.
• Trust domain policy: TrustDomainPolicy::AnyInBundleSet, which accepts any trust domain present in the source bundle set
• ALPN protocols: empty (no ALPN)

Production deployments should usually configure a more specific authorizer. Non-federated deployments should usually configure TrustDomainPolicy::LocalOnly.

pub fn authorize<A: Authorizer>(self, authorizer: A) -> Self

Sets the authorization policy for server SPIFFE IDs.

Accepts any type that implements Authorizer, including closures.

Examples

use spiffe_rustls::{authorizer, mtls_client};

let source = spiffe::X509Source::new().await?;

// Pass string literals directly
let config = mtls_client(source.clone())
    .authorize(authorizer::exact([
        "spiffe://example.org/service",
        "spiffe://example.org/service2",
    ])?)
    .build()?;

// Using a closure
let config = mtls_client(source.clone())
    .authorize(|id: &spiffe::SpiffeId| id.path().starts_with("/api/"))
    .build()?;

// Using the Any authorizer (default)
let config = mtls_client(source)
    .authorize(authorizer::any())
    .build()?;

pub fn trust_domain_policy(self, policy: TrustDomainPolicy) -> Self

Sets the trust domain policy.

Defaults to TrustDomainPolicy::AnyInBundleSet, which accepts any trust domain present in the source bundle set. For non-federated deployments, prefer TrustDomainPolicy::LocalOnly to restrict verification to the local trust domain.

pub fn with_alpn_protocols<I, P>(self, protocols: I) -> Self

where I: IntoIterator<Item = P>, P: AsRef<[u8]>,

Sets the ALPN (Application-Layer Protocol Negotiation) protocols.

The protocols are advertised during the TLS handshake. Common values:

• b"h2" for HTTP/2 (required for gRPC)
• b"http/1.1" for HTTP/1.1

Protocols should be specified in order of preference (most preferred first).

Examples

use spiffe_rustls::mtls_client;

let source = spiffe::X509Source::new().await?;
let config = mtls_client(source)
    .with_alpn_protocols([b"h2"])
    .build()?;

pub fn with_config_customizer<F>(self, customizer: F) -> Self

where F: FnOnce(&mut ClientConfig) + Send + 'static,

Applies a customizer function to the ClientConfig after it’s built.

This is an advanced API for configuration not directly exposed by the builder. The customizer is called last, after all other builder settings (including ALPN) have been applied, and gives direct access to the underlying rustls configuration.

Warning: Replacing the verifier or resolver disables SPIFFE authentication. Do not use this hook for that purpose; build a custom rustls configuration instead.

Examples

use spiffe_rustls::mtls_client;

let source = spiffe::X509Source::new().await?;
let config = mtls_client(source)
    .with_config_customizer(|cfg| {
        // Example: adjust cipher suite preferences
    })
    .build()?;

pub fn build(self) -> Result<ClientConfig>

Builds the rustls::ClientConfig.

The returned configuration:

• presents the current SPIFFE X.509 SVID as the client certificate
• validates the server certificate chain against trust bundles from the Workload API
• authorizes the server by SPIFFE ID (URI SAN)

The configuration is backed by a live X509Source. When the underlying SVID or trust bundle is rotated by the SPIRE agent, new TLS handshakes automatically use the updated material.

Errors

Returns an error if:

• the Rustls crypto provider is not installed
• no current X.509 SVID is available from the X509Source
• building the underlying Rustls certificate verifier fails

Trait Implementations

impl Debug for ClientConfigBuilder

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.