# spiffe
[](https://crates.io/crates/spiffe)
[](https://docs.rs/spiffe/)
[](https://github.com/rust-secure-code/safety-dance)
[](https://www.rust-lang.org)
A Rust library for interacting with the **SPIFFE Workload API**.
This crate 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](https://spiffe.io).
For the protocol definition, see the
[SPIFFE Workload API specification](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md).
---
## Installation
Add `spiffe` to your `Cargo.toml`. All features are opt-in:
```toml
[dependencies]
# Minimal: only SPIFFE primitives
spiffe = "0.11"
# OR X.509 workloads (recommended)
# spiffe = { version = "0.11", features = ["x509-source"] }
# OR JWT workloads (recommended)
# spiffe = { version = "0.11", features = ["jwt-source"] }
# OR Direct Workload API usage
# spiffe = { version = "0.11", features = ["workload-api"] }
```
---
## Quick start
### Create a Workload API client
Using an explicit socket path:
```rust
use spiffe::WorkloadApiClient;
let client = WorkloadApiClient::connect_to(
"unix:/tmp/spire-agent/public/api.sock",
).await?;
```
Or via the `SPIFFE_ENDPOINT_SOCKET` environment variable:
```rust
use spiffe::WorkloadApiClient;
let client = WorkloadApiClient::connect_env().await?;
```
---
## X.509 identities
The Workload API client exposes low-level access to X.509 materials.
```rust
use spiffe::{TrustDomain, X509Context};
let context: X509Context = client.fetch_x509_context().await?;
let trust_domain = TrustDomain::new("example.org")?;
let bundle = context
.bundle_set()
.get(&trust_domain)
.ok_or("missing bundle")?;
```
### Watch for updates
```rust
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.
```rust
use spiffe::{TrustDomain, X509Source};
let source = X509Source::new().await?;
// Snapshot of current materials
let context = source.x509_context()?;
// Selected SVID (default or picker)
let svid = source.svid()?;
// Bundle for a trust domain
let trust_domain = TrustDomain::new("example.org")?;
let bundle = source
.bundle_for_trust_domain(&trust_domain)?
.ok_or("missing bundle")?;
```
For most X.509-based workloads, **`X509Source` is the preferred API**.
---
## `JwtSource` (recommended)
`JwtSource` is a higher-level abstraction built on top of the Workload API for JWT workloads.
It maintains a locally cached, automatically refreshed view of JWT bundles,
handling reconnections and rotations transparently. JWT SVIDs are fetched on-demand
with specific audiences.
```rust
use spiffe::{TrustDomain, JwtSource};
let source = JwtSource::new().await?;
// Fetch JWT SVID for specific audiences
let jwt_svid = source.get_jwt_svid(&["service-a", "service-b"]).await?;
// Fetch JWT SVID for a specific SPIFFE ID
let spiffe_id = "spiffe://example.org/my-service".parse()?;
let jwt_svid = source.get_jwt_svid_with_id(&["audience"], Some(&spiffe_id)).await?;
// Bundle for a trust domain
let trust_domain = TrustDomain::new("example.org")?;
let bundle = source
.bundle_for_trust_domain(&trust_domain)?
.ok_or("missing bundle")?;
```
For most JWT-based workloads, **`JwtSource` is the preferred API**.
---
## SVID hints
When multiple SVIDs are returned by the Workload API, SPIRE may attach an
**operator-defined hint** (for example, `internal` or `external`) to guide selection.
Hints are **not part of the cryptographic identity**. They are metadata
returned by the Workload API and are exposed by this crate for convenience.
* X.509 hints are attached to `X509Svid`
* JWT hints are attached to `JwtSvid`
Higher-level abstractions like `X509Source` preserve hints and allow custom
selection logic via `SvidPicker`.
---
## JWT identities
### Using `JwtSource` (recommended)
For most JWT workloads, use `JwtSource` which provides automatic bundle caching and on-demand SVID fetching:
```rust
use spiffe::JwtSource;
let source = JwtSource::new().await?;
// Fetch JWT SVID
let jwt_svid = source.get_jwt_svid(&["audience1", "audience2"]).await?;
```
See the [`JwtSource`](#jwtsource-recommended) section above for more details.
### Direct Workload API access
For direct access without caching, use the Workload API client:
```rust
use spiffe::{SpiffeId, WorkloadApiClient};
let client = WorkloadApiClient::connect_env().await?;
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
```rust
use futures_util::StreamExt;
use spiffe::TrustDomain;
use spiffe::WorkloadApiClient;
let client = WorkloadApiClient::connect_env().await?;
let bundles = client.fetch_jwt_bundles().await?;
let trust_domain = TrustDomain::try_from("example.org")?;
let bundle = bundles.get(&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
}
```
---
## JWT verification modes
This crate supports **three distinct JWT-SVID usage patterns**, depending on where
verification happens.
### 1. Trusted by construction (no verification)
JWT-SVIDs **fetched directly from the SPIFFE Workload API** are trusted by construction.
The SPIRE agent already authenticated the workload and issued the token.
```rust
use spiffe::JwtSvid;
let svid = JwtSvid::from_workload_api_token(token_str)?;
```
No additional features are required.
---
### 2. Validation via the Workload API (recommended when available)
The Workload API exposes a validation RPC.
`WorkloadApiClient::validate_jwt_token` delegates verification to the SPIRE agent
and returns a parsed `JwtSvid`.
```rust
use spiffe::WorkloadApiClient;
let client = WorkloadApiClient::connect_env().await?;
let svid = client
.validate_jwt_token("my-audience", jwt_token)
.await?;
```
Characteristics:
* Signature verification is performed **by the SPIRE agent**
* No local cryptography required
* **Does not require any JWT verification feature**
* Recommended whenever the Workload API is reachable
---
### 3. Offline verification (explicit backend selection required)
If you need to validate **untrusted JWTs** locally (for example, tokens received
over the network), enable offline JWT verification with an explicit cryptographic
backend.
#### Using the pure-Rust backend (portable, recommended)
```toml
[dependencies]
spiffe = { version = "0.10", features = ["jwt-verify-rust-crypto"] }
```
#### Using the AWS-LC backend
```toml
[dependencies]
spiffe = { version = "0.10", features = ["jwt-verify-aws-lc-rs"] }
```
This enables local signature verification using JWT authorities from bundles:
```rust
use spiffe::JwtSvid;
let svid = JwtSvid::parse_and_validate(
token_str,
&bundle_source,
&["expected-audience"],
)?;
```
Use this mode when:
* The Workload API is not available
* Tokens are received from external peers
* Fully offline validation is required
---
## Features
All features are additive and opt-in. The crate has **no default features** (`default = []`).
### Core features
#### `x509`
Enables X.509 SVID and bundle types plus parsing. Gates heavy ASN.1/X.509 dependencies (`asn1`, `x509-parser`, `pkcs8`).
**Note:** Most users should enable `x509-source` instead, which includes this feature automatically.
#### `transport`
Lightweight endpoint parsing and normalization. No runtime dependencies (pure parsing logic).
#### `transport-grpc`
gRPC connector for Unix/TCP endpoints. Requires `transport` and adds tokio/tonic/tower dependencies.
#### `workload-api`
Enables the async SPIFFE Workload API client. Requires `transport-grpc` and `x509`.
Provides:
* `WorkloadApiClient` and streaming APIs
* X.509 and JWT SVID and bundle retrieval
* Streaming watch semantics
* Agent-side JWT validation (`validate_jwt_token`)
#### `x509-source`
High-level X.509 watcher and caching abstraction. Requires `workload-api` (and transitively `x509`).
Provides:
* `X509Source` for automatic SVID/bundle watching and caching
* Automatic reconnection and rotation handling
* Recommended for most X.509-based workloads
#### `jwt-source`
High-level JWT watcher and caching abstraction. Requires `workload-api` and `jwt`.
Provides:
* `JwtSource` for automatic bundle watching and caching
* On-demand JWT SVID fetching with audience specification
* Automatic reconnection and rotation handling
* Recommended for most JWT-based workloads
#### `jwt`
Enables JWT SVID and bundle types plus parsing. Gates JWT-related dependencies (`serde`, `serde_json`, `time`,
`base64ct`).
**Note:** JWT verification requires an additional backend feature (see below).
---
### JWT verification backends
#### `jwt-verify-rust-crypto`
Enables **offline JWT-SVID verification** using a **pure Rust cryptography backend**.
* Portable and dependency-light
* Recommended default for offline verification
* Required only when validating untrusted JWTs locally
---
### `jwt-verify-aws-lc-rs`
Enables **offline JWT-SVID verification** using **AWS-LC** via `aws-lc-rs`.
* Alternative cryptography backend
* Mutually exclusive with `jwt-verify-rust-crypto`
---
### Observability features
The crate supports optional observability through two mutually compatible features:
`logging` and `tracing`. Both features are optional and can be enabled independently
or together.
#### Feature precedence
When multiple observability features are enabled, the following precedence applies:
1. **`tracing`** (highest priority) — If enabled, all events are emitted via `tracing`
2. **`logging`** — If `tracing` is not enabled, events are emitted via the `log` crate
3. **No observability** — If neither feature is enabled, observability calls are no-ops
#### `logging`
Enables observability using the [`log`](https://crates.io/crates/log) crate.
This is a lightweight option suitable for applications that use the standard `log`
facade. Events are emitted via `log::debug!`, `log::info!`, `log::warn!`, and `log::error!`.
```toml
[dependencies]
spiffe = { version = "0.10", features = ["logging"] }
```
**Note:** The `logging` feature is not included in the default `workload-api` feature.
You must explicitly enable it if you want log output.
#### `tracing`
Enables structured observability using the [`tracing`](https://crates.io/crates/tracing) crate.
This is recommended for production environments that use structured logs, spans,
or distributed tracing systems. When both `tracing` and `logging` features are enabled,
**`tracing` takes precedence** and all events are emitted via `tracing` macros.
```toml
[dependencies]
spiffe = { version = "0.10", features = ["tracing"] }
```
**Note:** The `tracing` and `logging` features are not mutually exclusive. When both
features are enabled, events are emitted via `tracing`.
---
### Notes on JWT verification features
* Each backend feature (`jwt-verify-rust-crypto`, `jwt-verify-aws-lc-rs`) is self-contained and automatically includes
the `jwt` feature
* Exactly **one** offline verification backend must be selected (mutually exclusive)
* Offline verification features are **not required** when using `WorkloadApiClient::validate_jwt_token`
* X.509-based functionality is unaffected by JWT verification features
---
## Performance
The crate is designed for low-latency, high-throughput workloads:
- **Zero-copy parsing** where possible (X.509 DER, JWT parsing)
- **Efficient caching** in `X509Source` and `JwtSource` (atomic updates, no locks on read path)
- **Streaming APIs** for real-time updates without polling
- **Minimal allocations** in hot paths
The `X509Source` and `JwtSource` maintain cached views of SVIDs and bundles, updating atomically when the Workload API delivers new
material. This eliminates the need for polling and ensures new handshakes always use the latest credentials.
---
## Architecture
The crate is organized into several layers:
1. **Core primitives** (`SpiffeId`, `TrustDomain`) — Always available, no dependencies
2. **Transport layer** (`transport`, `transport-grpc`) — Endpoint parsing and gRPC connectivity
3. **Workload API client** (`workload-api-*`) — Low-level client for SPIFFE Workload API
4. **High-level abstractions** (`x509-source`, `jwt-source`) — Automatic caching and rotation handling
This layered design allows you to use only what you need, minimizing dependencies and compile times.
---
## Troubleshooting
### Common Issues
#### "Workload API connection failed"
- **Cause**: SPIRE agent not running or socket path incorrect
- **Solution**: Verify `SPIFFE_ENDPOINT_SOCKET` environment variable or socket path
#### "Empty response from Workload API"
- **Cause**: Workload not registered with SPIRE agent
- **Solution**: Ensure your workload is properly attested and registered
---
## Security Best Practices
- **Always validate JWT tokens** when received from untrusted sources (use `jwt-verify-*` features)
- **Use `X509Source` or `JwtSource`** for automatic rotation instead of manual polling
- **Enable observability** (`logging` or `tracing`) in production for monitoring
For security vulnerabilities, see [SECURITY.md](../SECURITY.md).
### Dependency advisories (cargo audit)
This project runs `cargo audit` in CI. Some advisories may appear only when enabling optional features
(e.g., offline JWT verification). At the time of writing, `cargo audit` may report `RUSTSEC-2023-0071`
(the `rsa` crate “Marvin Attack” advisory) via `jsonwebtoken`, and there is currently no fixed upgrade
available upstream.
If you require a clean audit, avoid enabling offline JWT verification unless needed, or temporarily ignore
the advisory until upstream releases a fix.
---
## Quick Reference
### Common Operations
| Create X.509 source | `X509Source::new().await?` |
| Create JWT source | `JwtSource::new().await?` |
| Get current SVID | `source.svid()?` |
| Get JWT SVID | `source.get_jwt_svid(&["aud"]).await?` |
| Get bundle | `source.bundle_for_trust_domain(&td)?.ok_or("missing")?` |
| Fetch JWT SVID (direct) | `client.fetch_jwt_svid(&["aud"], None).await?` |
| Parse SPIFFE ID | `SpiffeId::new("spiffe://td/path")?` |
| Check health | `source.is_healthy()` |
| Watch for updates | `source.updated()` |
### Error Handling
| `X509SourceError::NoSuitableSvid` | Picker rejects all SVIDs |
| `X509SourceError::Closed` | Source was shut down |
| `WorkloadApiError::EmptyResponse` | No data from Workload API |
| `SpiffeIdError::WrongScheme` | Invalid SPIFFE ID format |
---
## Documentation
Full API documentation and additional examples are available on
[docs.rs](https://docs.rs/spiffe).
---
## Changelog
See [CHANGELOG.md](../CHANGELOG.md) for version history and migration guides.
---
## License
Licensed under the Apache License, Version 2.0.
See [LICENSE](../LICENSE) for details.