Crate spiffe_rustls 

spiffe-rustls

spiffe-rustls integrates rustls with SPIFFE/SPIRE using a live spiffe::X509Source (SPIFFE Workload API).

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.

The crate focuses on TLS authentication and connection-level authorization via SPIFFE IDs, while delegating all cryptography and TLS mechanics to rustls.

Federation

When SPIFFE federation is configured, the Workload API delivers trust bundles for multiple trust domains. spiffe-rustls automatically handles this:

• The verifier extracts the peer’s SPIFFE ID from their certificate
• It derives the trust domain from that SPIFFE ID
• It selects the correct root certificate bundle from the bundle set
• Certificate verification proceeds using the selected bundle

No federation-specific configuration is required. Federation works automatically whenever the Workload API provides bundles for multiple trust domains. You can optionally restrict which trust domains are trusted using TrustDomainPolicy, but this is purely a defense-in-depth mechanism. Policy variants (AnyInBundleSet, AllowList, LocalOnly) are re-exported at the crate root for convenience.

Security Model

The crate follows a strict security model to ensure cryptographic verification is never bypassed:

1. SPIFFE ID extraction (pre-verification): The peer’s SPIFFE ID is extracted from the certificate’s URI SAN before cryptographic verification. This is safe because it is only used to select the trust domain’s root certificate bundle. The extracted SPIFFE ID has no security impact at this stage.

2. Cryptographic verification: Certificate verification (signature validation, chain validation, expiration checks) is performed by rustls/webpki using the selected root certificate bundle. This is the authoritative security boundary.

3. Authorization (post-verification): Authorization based on SPIFFE ID is applied only after cryptographic verification succeeds. If authorization fails, the handshake is rejected.

Failure modes: If the trust domain’s bundle is absent from the bundle set, or if the trust domain is rejected by policy, certificate verification fails and the handshake is rejected. This ensures that only cryptographically verified peers from allowed trust domains can establish connections.

Authorization

Authorization is performed after cryptographic verification succeeds. The crate provides a strongly-typed authorizer::Authorizer trait for implementing authorization policies.

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.

Re-exports

pub use authorizer::any;

pub use authorizer::exact;

pub use authorizer::trust_domains;

pub use authorizer::Authorizer;

pub use policy::TrustDomainPolicy::AllowList;

pub use policy::TrustDomainPolicy::AnyInBundleSet;

pub use policy::TrustDomainPolicy::LocalOnly;

Modules

authorizer

Authorization abstractions for SPIFFE ID-based access control.

Structs

ClientConfigBuilder

Builds a rustls::ClientConfig backed by a live SPIFFE X509Source.

ServerConfigBuilder

Builds a rustls::ServerConfig backed by a live SPIFFE X509Source.

SpiffeId

Represents a SPIFFE ID.

TrustDomain

Represents a SPIFFE Trust domain

Enums

Error

Errors returned by spiffe-rustls.

TrustDomainPolicy

Policy for selecting which trust domains to trust during certificate verification.

Functions

mtls_client

Convenience constructor for the mTLS client builder.

mtls_server

Convenience constructor for the mTLS server builder.

Type Aliases

Result

Result type used by this crate.