Package org.forgerock.secrets.keystore

Class KeyStoreSecretStore

java.lang.Object

org.forgerock.secrets.keystore.KeyStoreSecretStore

All Implemented Interfaces:

SecretStore<CryptoKey>

public class KeyStoreSecretStore
extends Object
implements SecretStore<CryptoKey>

A secret store for cryptographic keys based on a standard Java KeyStore. Typically this will either be a file-based PKCS#12 keystore or a PKCS#11 Hardware Security Module (HSM). Legacy proprietary key store formats such as JKS and JCEKS are also supported, but should not be used for any new functionality as they implement weak encryption and integrity protection mechanisms.

The password for the keystore and for all entries within the keystore can be provided as a GenericSecret allowing it to come from another secrets backend, such as an environment variable, encrypted file, KMS, etc.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	KeyStoreSecretStore.AliasSpec	Specifies an alias with its validity for use in the store.
class	KeyStoreSecretStore.KeyDetails	Details of a key that comes from the keystore.
static interface	KeyStoreSecretStore.StableIdProvider	An interface to allow the consuming application to provide the stable ID for the secret.

Field Summary

Fields inherited from interface org.forgerock.secrets.SecretStore

CLOCK, LEASE_EXPIRY_DURATION

Constructor Summary

Constructors

Constructor	Description
KeyStoreSecretStore(Function<char[],KeyStore,KeyStoreException> keyStoreLoader, SecretReference<GenericSecret> keyStorePassword)	Initialises the keystore using the same password for the keystore and all keys and default configuration options.
KeyStoreSecretStore(Function<char[],KeyStore,KeyStoreException> keyStoreLoader, SecretReference<GenericSecret> keyStorePassword, SecretReference<GenericSecret> keyEntryPassword, Options options, KeyStoreSecretStore.StableIdProvider stableIdProvider)	Initialises the key store.
KeyStoreSecretStore(Function<char[],KeyStore,KeyStoreException> keyStoreLoader, SecretReference<GenericSecret> keyStorePassword, Options options)	Initialises the keystore using the same password for the keystore and all keys.

Method Summary

Modifier and Type	Method	Description
<S extends CryptoKey> Promise<S,NoSuchSecretException>	getActive(Purpose<S> purpose)	Returns the active secret for the given purpose.
<S extends CryptoKey> Promise<S,NoSuchSecretException>	getNamed(Purpose<S> purpose, String id)	Returns the named secret from this store.
Class<CryptoKey>	getStoredType()	The top-level class that this store is capable of storing.
<S extends CryptoKey> 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.
void	retire(Purpose<? extends CryptoKey> purpose, String oldAlias)	Retires a key previously used for a given purpose.
void	revoke(String alias)	Revokes a key from all purposes.
void	rotate(Purpose<? extends CryptoKey> purpose, String newAlias)	Rotates the key associated with a given purpose.
void	setKeysForPurposes(Map<String,List<KeyStoreSecretStore.AliasSpec>> keysForPurposes)	Set the keys that are used for different purposes.
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

KeyStoreSecretStore

public KeyStoreSecretStore(Function<char[],KeyStore,KeyStoreException> keyStoreLoader,
                           SecretReference<GenericSecret> keyStorePassword,
                           SecretReference<GenericSecret> keyEntryPassword,
                           Options options,
                           KeyStoreSecretStore.StableIdProvider stableIdProvider)

Initialises the key store.

Parameters:

keyStoreLoader - the loader for the keystore. A function that takes the keystore password and returns the loaded keystore.

keyStorePassword - the keystore password.

keyEntryPassword - the key entry password. The same password will be used for all key entries.

options - the configuration options.

stableIdProvider - The implementation that will provide stable IDs for a given key.

KeyStoreSecretStore

public KeyStoreSecretStore(Function<char[],KeyStore,KeyStoreException> keyStoreLoader,
                           SecretReference<GenericSecret> keyStorePassword,
                           Options options)

Initialises the keystore using the same password for the keystore and all keys. Uses a default KeyStoreSecretStore.StableIdProvider that just returns KeyStoreSecretStore.KeyDetails.getAlias().

Parameters:

keyStoreLoader - the keystore loader.

keyStorePassword - the keystore password.

options - the configuration options.

KeyStoreSecretStore

public KeyStoreSecretStore(Function<char[],KeyStore,KeyStoreException> keyStoreLoader,
                           SecretReference<GenericSecret> keyStorePassword)

Initialises the keystore using the same password for the keystore and all keys and default configuration options. Uses a default KeyStoreSecretStore.StableIdProvider that just returns KeyStoreSecretStore.KeyDetails.getAlias().

Parameters:

keyStoreLoader - the keystore loader.

keyStorePassword - the keystore password.

Method Detail

setKeysForPurposes

public void setKeysForPurposes(Map<String,List<KeyStoreSecretStore.AliasSpec>> keysForPurposes)

Set the keys that are used for different purposes.

Parameters:

keysForPurposes - a map from purpose label to a list of key aliases.

rotate

public void rotate(Purpose<? extends CryptoKey> purpose,
                   String newAlias)

Rotates the key associated with a given purpose.

Specified by:

rotate in interface SecretStore<CryptoKey>

Parameters:

purpose - the purpose to install a new key for.

newAlias - the new key alias.

retire

public void retire(Purpose<? extends CryptoKey> purpose,
                   String oldAlias)

Retires a key previously used for a given purpose. The key will no longer be used for that purpose.

Specified by:

retire in interface SecretStore<CryptoKey>

Parameters:

purpose - the key purpose.

oldAlias - the key alias.

revoke

public void revoke(String alias)

Revokes a key from all purposes. The given key will no longer be usable for any purpose within this store.

Specified by:

revoke in interface SecretStore<CryptoKey>

Parameters:

alias - the alias to remove.

getStoredType

public Class<CryptoKey> getStoredType()

Description copied from interface: SecretStore

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.

Specified by:

getStoredType in interface SecretStore<CryptoKey>

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.

refresh

public void refresh()

Description copied from interface: SecretStore

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. Refresh may be an asynchronous operation and no guarantees are made about when clients of this secret store may see updated secrets after a call to refresh.

Specified by:

refresh in interface SecretStore<CryptoKey>

getActive

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

Description copied from interface: SecretStore

Returns the active secret for the given purpose.

Specified by:

getActive in interface SecretStore<CryptoKey>

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

public <S extends CryptoKey> Promise<S,NoSuchSecretException> getNamed(Purpose<S> purpose,
                                                                             String id)

Description copied from interface: SecretStore

Returns the named secret from this store.

Specified by:

getNamed in interface SecretStore<CryptoKey>

Type Parameters:

S - the type of secret.

Parameters:

purpose - the secret purpose.

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

Returns:

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

getValid

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

Description copied from interface: SecretStore

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

Specified by:

getValid in interface SecretStore<CryptoKey>

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.

toString

public String toString()

Overrides:

toString in class Object