hc_vault/
lib.rs

1#![warn(missing_docs)]
2//! Async, highly concurrent crate to interact with vault and its mounts
3
4/// The Approle Auth-Backend in vault
5pub mod approle;
6/// The Database module is used for all interactions with the database backend in vault
7pub mod database;
8/// The Kubernetes Auth-Backend in vault
9pub mod kubernetes;
10/// The kv2 module is used for all interactions with the v2 key-value backend in vault
11pub mod kv2;
12/// The token module is used for all basic interactions with a simple client-token and no other
13/// backend
14pub mod token;
15
16mod client;
17mod errors;
18mod internals;
19
20pub use client::*;
21pub use errors::*;
22
23/// This trait needs to be implemented by all auth backends to be used for
24/// authenticating using that backend
25pub trait Auth {
26    /// Checking if the current session is expired and needs to be renewed or dropped
27    ///
28    /// Safety:
29    /// This function is expected to be called from mulitple Threads at the same time
30    /// in an unsychronized way, even while the Auth-Backend is in the middle of an
31    /// Auth-Operation
32    fn is_expired(&self) -> bool;
33    /// Used to actually authenticate with the backend and obain a new valid session
34    /// that can be used for further requests to vault
35    ///
36    /// Safety:
37    /// This function is always called in a synchronized manner during which
38    /// no other Thread is readinh the Token. This allows for optimizations and
39    /// techniques to be used that rely on exclusive access to the Token when it
40    /// is being updated, but not while reading it. This helps to avoid any
41    /// Mutexes/Locks in the Auth-Backend.
42    fn auth(&self, vault_url: &str) -> Result<(), Error>;
43    /// Returns the vault token that can be used to make requests to vault
44    /// as the current session
45    ///
46    /// Safety:
47    /// This function is expected to be called from mulitple Threads at the same
48    /// time in an unsychronized way, but not while the Backend is doing a single
49    /// Auth-Operation
50    fn get_token(&self) -> String;
51    /// Returns if the current token can be renewed using this auth-backend.
52    /// This is used to decide whether or not to try to renew the session before
53    /// it is expired or letting the session expire and then simply obtaining a
54    /// new one the next time it is used.
55    ///
56    /// Safety:
57    /// This function is only called by a single, maybe two, threads.
58    fn is_renewable(&self) -> bool;
59    /// Returns the total duration for which the current token is valid for
60    /// in seconds
61    ///
62    /// Safety:
63    /// This function is only expected to be called by the background thread that
64    /// is responsible for renewing a token
65    fn get_total_duration(&self) -> u64;
66    /// This is used to actually renew the Tokens lease
67    ///
68    /// Safety:
69    /// This function is only expected to be called by the background thread that
70    /// renews the token
71    fn renew(&self, vault_url: &str) -> Result<(), Error>;
72}
73
74/// The RenewPolicy describes how the vault client should deal with expired
75/// vault session
76pub enum RenewPolicy {
77    /// Reauth causes the vault client to acquire a completly new vault session, via the
78    /// provided auth config, if the old one expired. This is a lazy operation,
79    /// so it only checks if it needs a new session before making a request
80    Reauth,
81    /// Renew causes the vault client to try and renew a token as long and as often as
82    /// possible without ever letting it actually expire.
83    /// The float should be a value between 0-1 and represents the percentage (0=0%, 1=100%)
84    /// of time that should be remaining before a session/token is renewed.
85    ///
86    /// Example:
87    /// With a threshold of 0.25 and a total Token Duration of 60m, the Token will be renewed
88    /// after 45m/ when only 15min are left.
89    Renew(f32),
90    /// Nothing does nothing when the session expires. This will cause the client to always
91    /// return a SessionExpired error when trying to request anything from vault
92    Nothing,
93}
94
95/// The Configuration for the vault client
96pub struct Config {
97    /// The URL the client should use to connect to the vault instance
98    pub vault_url: String,
99    /// The Policy the client should use to handle sessions expiring
100    ///
101    /// Default: RenewPolicy::Reauth
102    pub renew_policy: RenewPolicy,
103}
104
105impl Default for Config {
106    fn default() -> Config {
107        Config {
108            vault_url: "http://localhost:8200".to_string(),
109            renew_policy: RenewPolicy::Reauth,
110        }
111    }
112}
hc_vault/lib.rs

hc_vault/
lib.rs
