spiffe/
lib.rs

1#![deny(missing_docs)]
2#![warn(missing_debug_implementations)]
3
4//! This library provides functions to interact with the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md)
5//! to fetch X.509 and JWT SVIDs and Bundles. It also provides types that comply with the [SPIFFE standards](https://github.com/spiffe/spiffe/tree/main/standards).
6//!
7//! # Examples
8//!
9//! ```no_run
10//! use jsonwebtoken::jwk::Jwk;
11//! use spiffe::cert::{Certificate, PrivateKey};
12//! use spiffe::{
13//!     JwtBundle, JwtSvid, SpiffeId, TrustDomain, WorkloadApiClient, X509Bundle, X509BundleSet,
14//!     X509Context, X509Svid,
15//! };
16//! use std::convert::TryFrom;
17//! use std::error::Error;
18//!
19//! # async fn some_function() -> Result<(), Box< dyn Error>> {
20//!
21//! // create a new Workload API client connecting to the provided endpoint socket path
22//! let mut client =
23//!     WorkloadApiClient::new_from_path("unix:/tmp/spire-agent/api/public.sock").await?;
24//!
25//! // fetch the default X.509 SVID
26//! let x509_svid: X509Svid = client.fetch_x509_svid().await?;
27//!
28//! // fetch a set of X.509 bundles (X.509 public key authorities)
29//! let x509_bundles: X509BundleSet = client.fetch_x509_bundles().await?;
30//!
31//! // fetch all the X.509 materials (SVIDs and bundles)
32//! let x509_context: X509Context = client.fetch_x509_context().await?;
33//!
34//! // get the X.509 chain of certificates from the SVID
35//! let cert_chain: &Vec<Certificate> = x509_svid.cert_chain();
36//!
37//! // get the private key from the SVID
38//! let private_key: &PrivateKey = x509_svid.private_key();
39//!
40//! // parse a SPIFFE trust domain
41//! let trust_domain = TrustDomain::try_from("example.org")?;
42//!
43//! // get the X.509 bundle associated to the trust domain
44//! let x509_bundle: &X509Bundle = x509_bundles.get_bundle(&trust_domain).unwrap();
45//!
46//! // get the X.509 authorities (public keys) in the bundle
47//! let x509_authorities: &Vec<Certificate> = x509_bundle.authorities();
48//!
49//! // parse a SPIFFE ID
50//! let spiffe_id = SpiffeId::try_from("spiffe://example.org/my-service")?;
51//!
52//! let target_audience = &["service1", "service2"];
53//! // fetch a jwt token for the provided SPIFFE-ID and with the target audience `service1.com`
54//! let jwt_token = client
55//!     .fetch_jwt_token(target_audience, Some(&spiffe_id))
56//!     .await?;
57//!
58//! // fetch the jwt token and parses it as a `JwtSvid`
59//! let jwt_svid = client
60//!     .fetch_jwt_svid(target_audience, Some(&spiffe_id))
61//!     .await?;
62//!
63//! // fetch a set of jwt bundles (public keys for validating jwt token)
64//! let jwt_bundles_set = client.fetch_jwt_bundles().await?;
65//!
66//! // get the JWT bundle associated to the trust domain
67//! let jwt_bundle: &JwtBundle = jwt_bundles_set.get_bundle(&trust_domain).unwrap();
68//!
69//! // get the JWT authorities (public keys) in the bundle
70//! let jwt_authority: &Jwk = jwt_bundle.find_jwt_authority("a_key_id").unwrap();
71//!
72//! // parse a `JwtSvid` validating the token signature with a JWT bundle source.
73//! let validated_jwt_svid =
74//!     JwtSvid::parse_and_validate(&jwt_token, &jwt_bundles_set, &["service1.com"])?;
75//!
76//! # Ok(())
77//! # }
78//! ```
79
80#[cfg(feature = "spiffe-types")]
81pub mod constants;
82
83#[cfg(feature = "spiffe-types")]
84pub mod bundle;
85
86#[cfg(feature = "spiffe-types")]
87pub mod cert;
88
89#[cfg(feature = "spiffe-types")]
90pub mod spiffe_id;
91
92#[cfg(feature = "spiffe-types")]
93pub mod svid;
94
95#[cfg(feature = "spiffe-types")]
96pub mod error;
97
98#[cfg(feature = "spiffe-types")]
99pub mod endpoint;
100
101#[cfg(feature = "workload-api")]
102pub(crate) mod proto {
103    #![allow(clippy::all)]
104    pub(crate) mod workload {
105        include!(concat!(env!("OUT_DIR"), "/workload.rs"));
106    }
107}
108
109#[cfg(feature = "workload-api")]
110pub mod workload_api;
111
112// Core SPIFFE types and utilities re-exported for simplified access.
113pub use bundle::jwt::{JwtBundle, JwtBundleError, JwtBundleSet};
114pub use bundle::x509::{X509Bundle, X509BundleError, X509BundleSet};
115pub use bundle::BundleSource;
116pub use spiffe_id::{SpiffeId, SpiffeIdError, TrustDomain};
117pub use svid::jwt::{JwtSvid, JwtSvidError};
118pub use svid::x509::{X509Svid, X509SvidError};
119pub use svid::SvidSource;
120
121#[cfg(feature = "workload-api")]
122pub use workload_api::client::WorkloadApiClient;
123#[cfg(feature = "workload-api")]
124pub use workload_api::x509_context::X509Context;
125#[cfg(feature = "workload-api")]
126pub use workload_api::x509_source::{X509Source, X509SourceBuilder};
spiffe/lib.rs

spiffe/
lib.rs
