Struct bbjwt::keystore::KeyStore

pub struct KeyStore { /* private fields */ }

JWK key store.

This is basically a thin wrapper around JSON web key sets that adds loading/updating functionality.

Implementations

impl KeyStore

pub async fn new() -> BBResult<Self>

Create a new, empty keyset.

pub async fn new_from_url(surl: &str) -> BBResult<Self>

Create new keyset and load keys from a URL

Arguments

• surl: URL to load the keys from.

pub async fn keyset(&self) -> Vec<BBKey>

Return the keys in the keystore.

This function is cloning all keys, since otherwise the read lock would have to be held after this function returns. Thus, use this sparingly :-)

Returns

The cloned keyset.

pub async fn keys_len(&self) -> usize

Number of keys in keystore.

pub async fn add_key(&mut self, key_json: &str) -> BBResult<()>

Manually add a key to the keystore.

Arguments

• key_json - JSON string containing a JWK.

pub async fn add_rsa_pem_key( &self, pem: &str, kid: Option<&str>, alg: KeyAlgorithm ) -> BBResult<()>

Add a public RSA key from a PEM string.

Arguments

• pem - PEM encoded public RSA key
• kid - optional key id
• alg - algorithm, e.g. KeyAlgorithm::RS256

pub async fn add_ec_pem_key( &self, pem: &str, kid: Option<&str>, curve: EcCurve, alg: KeyAlgorithm ) -> BBResult<()>

Add a public elliptic curve key from a PEM string.

Supports both EdDSA and EC keys.

Arguments

• pem - public key in PEM encoding
• kid - optional key id
• curve - the Ed curve (Ed448 or Ed25519) or EC curve (P256, P384, P521)
• alg - the algorithm, e.g. ES384

pub async fn key_by_id(&self, kid: Option<&str>) -> BBResult<BBKey>

Retrieve a key by id.

The kid claim is optional, so the keyset may contain keys without id. This is why the kid argument to this function is optional, too. If it is None, we use the first key, assuming that there is only one. This complies to the rules set by the OpenID Connect spec, defined here.

Arguments

• kid - the ID of the key. If None, the first key is returned.

pub fn set_reload_factor(&mut self, interval: f64)

Specify the interval factor to determine when the key store should reload its keys.

The default is 0.75, meaning that keys should be reloaded when we are 3/4 through the expiration time (similar to DHCP). For example if the server tells us that the keys expire in 10 minutes, setting the reload interval to 0.75 will consider the keys to be expired after 7.5 minutes and the KeyStore::should_reload function returns true.

This method does not update the reload time. Call KeyStore::load_keys to force an update.

pub fn reload_factor(&self) -> f64

Get the current fraction time to check for token reload time.

pub fn load_time(&self) -> Option<SystemTime>

Get the time at which the keys were initially loaded.

Returns

Time of initial load or None if the keys were never loaded.

pub fn reload_time(&self) -> Option<SystemTime>

Get the time at which the keys should be reloaded.

See KeyStore::set_reload_factor for more info.

pub fn should_reload_time(&self, time: SystemTime) -> Option<bool>

Check if keys are expired based on the given time.

Returns

• Some(true) if keys should be reloaded.
• Some(false) if keys need not to be reloaded
• None if the key store does not have a reload time available. For example, the KeyStore::load_keys function was not called or the HTTP server did not provide a cache-control HTTP header.

pub fn should_reload(&self) -> Option<bool>

Check if keys are expired based on the current system time.

Returns

• Some(true) if keys should be reloaded.
• Some(false) if keys need not to be reloaded
• None if the key store does not have a reload time available. For example, the KeyStore::load_keys function was not called or the HTTP server did not provide a cache-control HTTP header.

pub async fn load_keys(&mut self) -> BBResult<()>

Load/update keys from the keystore URL.

Clients should call this function when KeyStore::should_reload returns true.

pub async fn idp_certs_url(idp_discovery_url: &str) -> BBResult<String>

Determine the URL where public keys can be loaded.

OpenID Connect IdPs provide an info endpoint called OpenID Connect Discovery that returns, among other info, the URL where the IdP’s public keys (JWKS) are downloadable. These public keys are used to validate ID Tokens (i.e. JWTs) issued by this IdP.

This function returns the public keys URL read from the discovery endpoint.

OpenID Connect providers might use different schemas for this URL; for Keycloak, the URL is built like this:

https://host.tld/realms/<realm_name>/.well-known/openid-configuration

Arguments

• idp_discovery_url - the URL to load the discovery info from.

pub fn keycloak_discovery_url(host: &str, realm: &str) -> BBResult<String>

Construct Keycloak specific discovery URL from a host and realm name.

Provided for convenience :-)

Arguments

• host - protocol and host name of the Keycloak server, e.g. https://idp.domain.tld
• realm - the realm name

Returns

URL of discovery endpoint.

Trait Implementations

impl Debug for KeyStore

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.