org.forgerock.secrets

Interface SecretStore<T extends Secret>

Type Parameters:

T - the type of secrets that this backend can store.

All Known Implementing Classes:

JwkSetSecretStore, KeyStoreSecretStore, PropertyResolverSecretStore, ThreadPoolSecretStore

public interface SecretStore<T extends Secret>

A backend storage mechanism for certain kinds of secrets. Unlike a SecretsProvider a store may only be capable of storing certain types of secrets.

Field Summary

Fields

Modifier and Type	Field and Description
static Option<Clock>	CLOCK Option used to specify how long secrets from a store should be used before being refreshed.
static Option<Duration>	LEASE_EXPIRY_DURATION Option used to specify how long secrets from a store should be used before being refreshed.

Method Summary

Modifier and Type	Method and Description
<S extends T> Promise<S,NoSuchSecretException>	getActive(Purpose<S> purpose) Returns the active secret for the given purpose.
<S extends T> Promise<S,NoSuchSecretException>	getNamed(Purpose<S> purpose, String name) Returns the named secret from this store.
Class<T>	getStoredType() The top-level class that this store is capable of storing.
<S extends T> Promise<Stream<S>,NeverThrowsException>	getValid(Purpose<S> purpose) Returns all valid secrets for the given purpose from this store.
void	refresh() Indicates that the store should refresh its secrets from the backing storage mechanism.
default void	retire(Purpose<? extends T> purpose, String secretIdToRetire) Retires the given secret for the given purpose.
default void	revoke(String secretId) Revokes the given secret for all purposes in this store.
default void	rotate(Purpose<? extends T> purpose, String newActiveSecretId) Rotates the active secret for the given purpose.

Field Detail

LEASE_EXPIRY_DURATION

static final Option<Duration> LEASE_EXPIRY_DURATION

Option used to specify how long secrets from a store should be used before being refreshed. Defaults to 5 minutes.

CLOCK

static final Option<Clock> CLOCK

Option used to specify how long secrets from a store should be used before being refreshed. Defaults to 5 minutes.

Method Detail

getStoredType

Class<T> getStoredType()

The top-level class that this store is capable of storing. This is a reification of the type parameter and can be used to lookup stores for a given type.

Returns:

the top-most type that this store is capable of storing, typically either CryptoKey for key-stores, GenericSecret for password stores, or Secret if the store is capable of storing any type of secret.

getActive

<S extends T> Promise<S,NoSuchSecretException> getActive(Purpose<S> purpose)

Returns the active secret for the given purpose.

Type Parameters:

S - the type of secret.

Parameters:

purpose - the purpose for which a secret is required.

Returns:

the active secret from this store.

getNamed

<S extends T> Promise<S,NoSuchSecretException> getNamed(Purpose<S> purpose,
                                                        String name)

Returns the named secret from this store.

Type Parameters:

S - the type of secret.

Parameters:

purpose - the secret purpose.

name - the name (stable id) of the secret.

Returns:

the named secret, or Optional.empty() if no such secret exists.

getValid

<S extends T> Promise<Stream<S>,NeverThrowsException> getValid(Purpose<S> purpose)

Returns all valid secrets for the given purpose from this store.

Type Parameters:

S - the type of secret.

Parameters:

purpose - the purpose.

Returns:

a stream of all valid secrets of the given type from this store, or an empty stream if none exist.

refresh

void refresh()

Indicates that the store should refresh its secrets from the backing storage mechanism. This can be used to cause reload of a store after a secret rotation if the backend does not automatically detect such changes.

rotate

default void rotate(Purpose<? extends T> purpose,
                    String newActiveSecretId)

Rotates the active secret for the given purpose. The secret with the given stable id will be used as the active secret after this method completes, while the previous active secret will still be available as a named or valid secret until it is retired. This is an optional operation and will throw UnsupportedOperationException if the store does not implement rotation directly. Some stores natively support rotation, in which case this should be done using store-specific interfaces.

Parameters:

purpose - the purpose for which to rotate the active secret.

newActiveSecretId - the stable id of the new active secret.

Throws:

IllegalArgumentException - if there is no such secret in this store, or if it is inappropriate for this purpose.

UnsupportedOperationException - if this store does not support direct secret rotation.

retire

default void retire(Purpose<? extends T> purpose,
                    String secretIdToRetire)

Retires the given secret for the given purpose. The named secret will no longer be considered valid for this purpose. This is an optional operation and will throw UnsupportedOperationException if the store does not implement rotation directly. Some stores natively support rotation, in which case this should be done using store-specific interfaces. If the given secret is the current active secret for the purpose then the previous active secret will become active. If there are no still-valid previous secrets then there will be no active secret for that purpose and any attempts to use it will generate NoSuchSecretExceptions.

Parameters:

purpose - the purpose for which to retire the secret.

secretIdToRetire - the stable id of the secret to retire.

Throws:

UnsupportedOperationException - if this store does not support direct secret rotation.

revoke

default void revoke(String secretId)

Revokes the given secret for all purposes in this store. The named secret will no longer be available as an active, named or valid secret for any purpose. If the given secret is currently the active secret for any purpose, then the store will revert to using the previous active secret for that purpose. If no previous secret is still valid then there will be no active secret for that purpose and any attempts to use it will generate a NoSuchSecretException. It is therefore advised to rotate a new secret into use for all such purposes before revoking the active secret.

Note that if the store does not contain the named secret then it will silently ignore this request.

Parameters:

secretId - the stable id of the secret to revoke.

Throws:

UnsupportedOperationException - if the store does not support directly revoking secrets.