spiffe

A Rust library for interacting with the SPIFFE Workload API.

It provides idiomatic, standards-compliant access to SPIFFE identities and trust material, including:

• X.509 SVIDs and trust bundles
• JWT SVIDs and JWT bundles
• Streaming updates (watch semantics)
• Strongly typed SPIFFE primitives aligned with the SPIFFE specifications

For an introduction to SPIFFE, see https://spiffe.io.
For the protocol definition, see the SPIFFE Workload API specification.

Installation

Add spiffe to your Cargo.toml:

[dependencies]
spiffe = "0.7.4"

Quick start

Create a Workload API client

Using an explicit socket path:

use spiffe::WorkloadApiClient;

let client = WorkloadApiClient::new_from_path(
    "unix:///tmp/spire-agent/public/api.sock",
).await?;

Or via the SPIFFE_ENDPOINT_SOCKET environment variable:

use spiffe::WorkloadApiClient;

let client = WorkloadApiClient::default().await?;

X.509 identities

The Workload API client exposes low-level access to X.509 materials.

use spiffe::{TrustDomain, X509Context};

let svid = client.fetch_x509_svid().await?;
let bundles = client.fetch_x509_bundles().await?;
let context: X509Context = client.fetch_x509_context().await?;

let trust_domain = TrustDomain::try_from("example.org")?;
let bundle = bundles.get_bundle(&trust_domain)?;

Watch for updates

use futures_util::StreamExt;

let mut stream = client.stream_x509_contexts().await?;

while let Some(update) = stream.next().await {
    let context = update?;
    // react to updated SVIDs and bundles
}

X509Source (recommended)

X509Source is a higher-level abstraction built on top of the Workload API.

It maintains a locally cached, automatically refreshed view of X.509 SVIDs and bundles, handling reconnections and rotations transparently.

use spiffe::{TrustDomain, X509Source};

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

// Snapshot of current materials
let context = source.x509_context();

// Default SVID
let svid = context.default_svid()?;

// Bundle for a trust domain
let trust_domain = TrustDomain::try_from("example.org")?;
let bundle = context.bundles().get_bundle(&trust_domain)?;

For most X.509-based workloads, X509Source is the preferred API.

JWT identities

JWT-based identity is accessed directly via the Workload API client.

Fetch JWT SVIDs

use spiffe::SpiffeId;

let spiffe_id = SpiffeId::try_from("spiffe://example.org/my-service")?;

let jwt = client
    .fetch_jwt_svid(&["audience1", "audience2"], Some(&spiffe_id))
    .await?;

Fetch and watch JWT bundles

use futures_util::StreamExt;
use spiffe::TrustDomain;

let bundles = client.fetch_jwt_bundles().await?;
let trust_domain = TrustDomain::try_from("example.org")?;
let bundle = bundles.get_bundle(&trust_domain)?;

let mut stream = client.stream_jwt_bundles().await?;
while let Some(update) = stream.next().await {
    let bundles = update?;
    // react to updated JWT authorities
}

Documentation

Full API documentation and additional examples are available on docs.rs.

License

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