spiffe/
lib.rs

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
#![deny(missing_docs)]
#![warn(missing_debug_implementations)]

//! This library provides functions to interact with the [SPIFFE Workload API](https://github.com/spiffe/spiffe/blob/main/standards/SPIFFE_Workload_API.md)
//! 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).
//!
//! # Examples
//!
//! ```no_run
//! use jsonwebtoken::jwk::Jwk;
//! use spiffe::cert::{Certificate, PrivateKey};
//! use spiffe::{
//!     JwtBundle, JwtSvid, SpiffeId, TrustDomain, WorkloadApiClient, X509Bundle, X509BundleSet,
//!     X509Context, X509Svid,
//! };
//! use std::convert::TryFrom;
//! use std::error::Error;
//!
//! # async fn some_function() -> Result<(), Box< dyn Error>> {
//!
//! // create a new Workload API client connecting to the provided endpoint socket path
//! let mut client =
//!     WorkloadApiClient::new_from_path("unix:/tmp/spire-agent/api/public.sock").await?;
//!
//! // fetch the default X.509 SVID
//! let x509_svid: X509Svid = client.fetch_x509_svid().await?;
//!
//! // fetch a set of X.509 bundles (X.509 public key authorities)
//! let x509_bundles: X509BundleSet = client.fetch_x509_bundles().await?;
//!
//! // fetch all the X.509 materials (SVIDs and bundles)
//! let x509_context: X509Context = client.fetch_x509_context().await?;
//!
//! // get the X.509 chain of certificates from the SVID
//! let cert_chain: &Vec<Certificate> = x509_svid.cert_chain();
//!
//! // get the private key from the SVID
//! let private_key: &PrivateKey = x509_svid.private_key();
//!
//! // parse a SPIFFE trust domain
//! let trust_domain = TrustDomain::try_from("example.org")?;
//!
//! // get the X.509 bundle associated to the trust domain
//! let x509_bundle: &X509Bundle = x509_bundles.get_bundle(&trust_domain).unwrap();
//!
//! // get the X.509 authorities (public keys) in the bundle
//! let x509_authorities: &Vec<Certificate> = x509_bundle.authorities();
//!
//! // parse a SPIFFE ID
//! let spiffe_id = SpiffeId::try_from("spiffe://example.org/my-service")?;
//!
//! let target_audience = &["service1", "service2"];
//! // fetch a jwt token for the provided SPIFFE-ID and with the target audience `service1.com`
//! let jwt_token = client
//!     .fetch_jwt_token(target_audience, Some(&spiffe_id))
//!     .await?;
//!
//! // fetch the jwt token and parses it as a `JwtSvid`
//! let jwt_svid = client
//!     .fetch_jwt_svid(target_audience, Some(&spiffe_id))
//!     .await?;
//!
//! // fetch a set of jwt bundles (public keys for validating jwt token)
//! let jwt_bundles_set = client.fetch_jwt_bundles().await?;
//!
//! // get the JWT bundle associated to the trust domain
//! let jwt_bundle: &JwtBundle = jwt_bundles_set.get_bundle(&trust_domain).unwrap();
//!
//! // get the JWT authorities (public keys) in the bundle
//! let jwt_authority: &Jwk = jwt_bundle.find_jwt_authority("a_key_id").unwrap();
//!
//! // parse a `JwtSvid` validating the token signature with a JWT bundle source.
//! let validated_jwt_svid =
//!     JwtSvid::parse_and_validate(&jwt_token, &jwt_bundles_set, &["service1.com"])?;
//!
//! # Ok(())
//! # }
//! ```

#[cfg(feature = "spiffe-types")]
pub mod constants;

#[cfg(feature = "spiffe-types")]
pub mod bundle;

#[cfg(feature = "spiffe-types")]
pub mod cert;

#[cfg(feature = "spiffe-types")]
pub mod spiffe_id;

#[cfg(feature = "spiffe-types")]
pub mod svid;

#[cfg(feature = "spiffe-types")]
pub mod error;

#[cfg(feature = "spiffe-types")]
pub mod endpoint;

#[cfg(feature = "workload-api")]
pub(crate) mod proto {
    #![allow(clippy::all)]
    pub(crate) mod workload {
        include!(concat!(env!("OUT_DIR"), "/workload.rs"));
    }
}

#[cfg(feature = "workload-api")]
pub mod workload_api;

// Core SPIFFE types and utilities re-exported for simplified access.
pub use bundle::jwt::{JwtBundle, JwtBundleError, JwtBundleSet};
pub use bundle::x509::{X509Bundle, X509BundleError, X509BundleSet};
pub use bundle::BundleSource;
pub use spiffe_id::{SpiffeId, SpiffeIdError, TrustDomain};
pub use svid::jwt::{JwtSvid, JwtSvidError};
pub use svid::x509::{X509Svid, X509SvidError};
pub use svid::SvidSource;

#[cfg(feature = "workload-api")]
pub use workload_api::client::WorkloadApiClient;
#[cfg(feature = "workload-api")]
pub use workload_api::x509_context::X509Context;
#[cfg(feature = "workload-api")]
pub use workload_api::x509_source::{X509Source, X509SourceBuilder};