spiffe-rustls-tokio

Tokio-native async accept/connect helpers for spiffe-rustls configs.

Integrates tokio-rustls with automatic peer SPIFFE ID extraction. Provides TlsAcceptor and TlsConnector that return (TlsStream, PeerIdentity) after successful handshakes. Runtime-agnostic TLS configuration remains in spiffe-rustls.

Installation

Add spiffe-rustls-tokio to your Cargo.toml:

[dependencies]
spiffe-rustls-tokio = "0.1"
spiffe-rustls = "0.4"
spiffe = { version = "0.11", features = ["x509-source"] }

Quick Start

1. Create a `spiffe-rustls` configuration

use spiffe::X509Source;
use spiffe_rustls::{authorizer, mtls_client};

let source = X509Source::new().await?;
let client_config = mtls_client(source)
    .authorize(authorizer::any())
    .build()?;

2. Use `TlsConnector` or `TlsAcceptor`

use spiffe_rustls_tokio::TlsConnector;
use std::sync::Arc;

let connector = TlsConnector::new(Arc::new(client_config));
// ... use connector.connect() or connector.connect_addr()

Example: Using `connect_addr` Convenience Method

use spiffe::X509Source;
use spiffe_rustls::{authorizer, mtls_client};
use spiffe_rustls_tokio::TlsConnector;
use std::net::SocketAddr;
use std::sync::Arc;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let source = X509Source::new().await?;
    let client_config = mtls_client(source)
        .authorize(authorizer::any())
        .build()?;

    let connector = TlsConnector::new(Arc::new(client_config));
    let addr: SocketAddr = "127.0.0.1:8443".parse()?;
    let server_name = rustls::pki_types::ServerName::try_from("example.org")?;

    // connect_addr combines TCP connection and TLS handshake
    match connector.connect_addr(addr, server_name).await {
        Ok((tls_stream, peer_identity)) => {
            if let Some(spiffe_id) = peer_identity.spiffe_id() {
                println!("Connected (SPIFFE ID: {})", spiffe_id);
            }
            // Use tls_stream...
        }
        Err(e) => eprintln!("Connection failed: {}", e),
    }

    Ok(())
}

API Overview

Main Types

TlsAcceptor — Server-side TLS acceptor that extracts peer SPIFFE identity
TlsConnector — Client-side TLS connector that extracts peer SPIFFE identity
PeerIdentity — Contains the extracted SPIFFE ID from the peer certificate
Error — Error type for TLS and identity extraction failures

Key Methods

TlsAcceptor::accept() — Accepts a TLS connection and returns (TlsStream, PeerIdentity)
TlsConnector::connect() — Establishes a TLS connection and returns (TlsStream, PeerIdentity)
TlsConnector::connect_addr() — Convenience method that combines TCP connection and TLS handshake
PeerIdentity::spiffe_id() — Returns the peer's SPIFFE ID, if present

Examples

The crate includes complete working examples that demonstrate real mTLS connections using SPIRE.

Prerequisites

A running SPIRE agent with Workload API accessible
The SPIFFE_ENDPOINT_SOCKET environment variable set (or use default Unix socket path)
Both client and server workloads registered with SPIRE

Running the Examples

The examples are located in the examples/ directory:

mtls_tcp_server - A server that accepts mTLS connections and extracts peer SPIFFE IDs
mtls_tcp_client - A client that connects to the server and extracts peer SPIFFE IDs

To run the examples:

# Terminal 1: Start the server
cargo run --package spiffe-rustls-tokio --example mtls_tcp_server

# Terminal 2: Run the client
cargo run --package spiffe-rustls-tokio --example mtls_tcp_client

The examples will:

Connect to SPIRE via the Workload API to obtain X.509 SVIDs and trust bundles
Perform mutual TLS handshakes with automatic certificate rotation support
Extract and display peer SPIFFE IDs from certificates
Exchange messages over the encrypted connection

The server listens on 127.0.0.1:8443 by default. Both examples demonstrate:

Authorization policies (trust domains, exact SPIFFE IDs)
Trust domain policies (LocalOnly, AllowList)
Peer identity extraction using PeerIdentity::spiffe_id()
Error handling for TLS and identity extraction failures

Peer Identity Extraction

After a successful TLS handshake, the peer's SPIFFE ID is extracted from their certificate's URI SAN.

According to the SPIFFE specification, an X.509-SVID must contain exactly one SPIFFE ID. When using spiffe-rustls verifiers correctly, this is enforced during the TLS handshake.

API behavior:

Exactly one SPIFFE ID: Extracted and stored in PeerIdentity::spiffe_id
Missing/multiple SPIFFE IDs or no peer certificates: spiffe_id is None (no error; accept()/connect() succeed)
Certificate parse failure: Returns Error::CertParse (accept()/connect() fail)

A None value for spiffe_id is unexpected in SPIFFE-compliant configurations and may indicate misconfiguration or a non-SPIFFE peer.

License

Licensed under the Apache License, Version 2.0.

spiffe-rustls-tokio 0.1.1