spiffe/
lib.rs

1#![deny(missing_docs)]
2#![warn(missing_debug_implementations)]
3
4//! This crate provides Rust bindings for the
5//! [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md).
6//!
7//! It allows workloads to fetch and watch SPIFFE-issued X.509 and JWT SVIDs,
8//! trust bundles, and related metadata, using strongly typed APIs that comply
9//! with the SPIFFE standards.
10//!
11//! The primary entry point for X.509-based workloads is [`X509Source`], which
12//! maintains a live connection to the Workload API and automatically tracks
13//! SVID and bundle rotation.
14//!
15//! ## X.509 (recommended)
16//!
17//! ```no_run
18//! use spiffe::{TrustDomain, X509Source};
19//!
20//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
21//! // Connect to the Workload API using SPIFFE_ENDPOINT_SOCKET
22//! let source = X509Source::new().await?;
23//!
24//! // Get the current X.509 context (SVIDs + bundles)
25//! let context = source.x509_context()?;
26//!
27//! // Access the default SVID
28//! let svid = context.default_svid().ok_or("missing svid")?;
29//!
30//! // Inspect the certificate chain and private key
31//! let cert_chain = svid.cert_chain();
32//! let private_key = svid.private_key();
33//!
34//! // Access trust bundles by trust domain
35//! let trust_domain = TrustDomain::try_from("example.org")?;
36//! let bundle = context.bundle_set().get_bundle(&trust_domain).unwrap();
37//!
38//! # source.shutdown().await?;
39//! # Ok(())
40//! # }
41//! ```
42//!
43//! ## JWT SVIDs
44//!
45//! JWT-based identity is supported via [`WorkloadApiClient`] and related types.
46//!
47//! ```no_run
48//! use spiffe::{JwtSvid, WorkloadApiClient};
49//!
50//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
51//! let mut client = WorkloadApiClient::default().await?;
52//!
53//! let audiences = &["service-a"];
54//! let jwt_svid = client.fetch_jwt_svid(audiences, None).await?;
55//!
56//! let claims = jwt_svid.claims();
57//! # Ok(())
58//! # }
59//! ```
60//!
61//! ## Features
62//!
63//! - **`spiffe-types`**: Core SPIFFE types (IDs, SVIDs, bundles)
64//! - **`workload-api`**: Workload API client and streaming support
65//!
66//! Most users should enable both features (default).
67
68#[cfg(feature = "spiffe-types")]
69pub mod constants;
70
71#[cfg(feature = "spiffe-types")]
72pub mod bundle;
73
74#[cfg(feature = "spiffe-types")]
75pub mod cert;
76
77#[cfg(feature = "spiffe-types")]
78pub mod spiffe_id;
79
80#[cfg(feature = "spiffe-types")]
81pub mod svid;
82
83#[cfg(feature = "spiffe-types")]
84pub mod error;
85
86#[cfg(feature = "spiffe-types")]
87pub mod endpoint;
88
89#[cfg(feature = "workload-api")]
90pub mod workload_api;
91
92// -----------------------
93// Re-exports
94// -----------------------
95
96/// Core SPIFFE types and utilities re-exported for simplified access.
97#[cfg(feature = "spiffe-types")]
98pub use crate::{
99    bundle::jwt::{JwtBundle, JwtBundleError, JwtBundleSet},
100    bundle::x509::{X509Bundle, X509BundleError, X509BundleSet},
101    bundle::BundleSource,
102    spiffe_id::{SpiffeId, SpiffeIdError, TrustDomain},
103    svid::jwt::{JwtSvid, JwtSvidError},
104    svid::x509::{X509Svid, X509SvidError},
105    svid::SvidSource,
106};
107
108#[cfg(feature = "workload-api")]
109pub use crate::workload_api::client::WorkloadApiClient;
110
111#[cfg(feature = "workload-api")]
112pub use crate::workload_api::x509_context::X509Context;
113
114#[cfg(feature = "workload-api")]
115pub use crate::workload_api::x509_source::{X509Source, X509SourceBuilder};
spiffe/lib.rs

spiffe/
lib.rs
