spiffe-rustls

spiffe-rustls integrates rustls with SPIFFE/SPIRE using the spiffe crate’s X509Source (SPIFFE Workload API).

It provides builders for rustls::ClientConfig and rustls::ServerConfig backed by a live X509Source. When the SPIRE agent rotates 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.

Quick start

1. Create an X509Source

The source is configured via SPIFFE_ENDPOINT_SOCKET:

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

2. Build a rustls client configuration

use spiffe_rustls::{ClientConfigBuilder, ClientConfigOptions};
use std::sync::Arc;

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?;

The resulting ClientConfig can be used directly with rustls, or integrated into tokio-rustls, tonic-rustls, or similar libraries.

API overview

The public API is intentionally small and consists of two builders:

ClientConfigBuilder
ServerConfigBuilder

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)

ClientConfigBuilder

Builds a rustls::ClientConfig that:

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)

ServerConfigBuilder

Builds a rustls::ServerConfig that:

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)

Options

ClientConfigOptions

pub struct ClientConfigOptions {
    pub trust_domain: TrustDomain,
    pub authorize_server: AuthorizeSpiffeId,
}

trust_domain: trust domain whose bundle is used as the root of trust
authorize_server: authorization hook invoked with the server SPIFFE ID

Use ClientConfigOptions::allow_any(trust_domain) to disable authorization while retaining full authentication.

ServerConfigOptions

pub struct ServerConfigOptions {
    pub trust_domain: TrustDomain,
    pub authorize_client: AuthorizeSpiffeId,
}

trust_domain: trust domain whose bundle is used as the root of trust
authorize_client: authorization hook invoked with the client SPIFFE ID

Use ServerConfigOptions::allow_any(trust_domain) to disable authorization while retaining full authentication.

Features

spiffe-rustls supports multiple rustls crypto providers:

[features]
default = ["ring"]
ring = ["rustls/ring"]
aws-lc-rs = ["rustls/aws_lc_rs"]

Default: ring
Optional: aws-lc-rs

Exactly one provider must be enabled. Enabling more than one results in a compile-time error.

Example (AWS-LC):

cargo add spiffe-rustls --no-default-features --features aws-lc-rs

Provider choice affects only cryptographic primitives; SPIFFE semantics and API behavior are identical across providers.

Examples

Prerequisites

All examples require:

a running SPIRE agent
a valid Workload API socket (SPIFFE_ENDPOINT_SOCKET)
local DNS resolution for example.org

For local testing, add to /etc/hosts:

127.0.0.1 example.org

Raw TLS (tokio-rustls)

Direct TLS integration using tokio-rustls.

Examples:

mtls_tcp_server.rs
mtls_tcp_client.rs

cargo run --features tcp-examples --example mtls_tcp_server
cargo run --features tcp-examples --example mtls_tcp_client

gRPC (tonic + tonic-rustls)

gRPC examples live in a separate crate (spiffe-rustls-grpc-examples) to avoid pulling gRPC and protobuf build dependencies into the library.

cargo run -p spiffe-rustls-grpc-examples --bin grpc_server_mtls
cargo run -p spiffe-rustls-grpc-examples --bin grpc_client_mtls

Notes

Examples rely exclusively on the SPIFFE Workload API; they do not start or configure SPIRE.
Standard TLS name (SNI) verification still applies; the DNS name must match the certificate SAN.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

spiffe-rustls 0.1.3