Package org.forgerock.secrets

Class SecretsProvider

java.lang.Object
org.forgerock.secrets.SecretsProvider
public class SecretsProvider extends Object
The secrets provider is used to get hold of active, named or valid secret objects. An active secret is the preferred secret to use for a particular Purpose at a given point in time. The active secret may change over time as the old secret is revoked or rotated. Previously active secrets can be looked up using getNamedSecret(Purpose, String) using the secret's stable id. Alternatively, all still-valid secrets for a given purpose can be obtained via the getValidSecrets(Purpose) method.

As not all secret storage backends are appropriate for storing all kinds of secrets, the provider allows different SecretStores to be configured for one or more different purposes, via the setActiveStore(SecretStore, Purpose[]) method. This installs the provided store as the preferred storage backend for that purpose. All requests for active secrets for that purpose will be routed to that backend. Any previously configured stores for that purpose will be retained but only queried to find existing named or valid secrets.

A set of default stores can be configured using setDefaultStores(SecretStore, SecretStore[]). These stores will be consulted if no specific store has been configured for a particular purpose. By default there is no default store and so a NoSuchSecretException is thrown by any attempt to access a secret for a purpose without a specific store configured.

  • Constructor Details

    • SecretsProvider

      @Deprecated public SecretsProvider()
      Deprecated.
      Prefer using SecretsProvider(Clock) and provide your own clock instance.
      Constructs a SecretsProvider, using the default system UTC clock to check if a secret has expired.

    • SecretsProvider

      public SecretsProvider(Clock clock)
      Constructs a SecretsProvider, using the provided clock to check if a secret has expired.
      Parameters:
      clock - the clock to use when checking if the secret has expired.

  • Method Details

    • setActiveStore

      @SafeVarargs public final <T extends Secret> SecretsProvider setActiveStore(SecretStore<? super T> store, Purpose<? extends T>... purposes)
      Sets the active store to use for the given purpose. All existing stores for that purpose will be deactivated and will only be used to serve requests for existing keys that are still valid rather than to produce new active keys.

      This method delegates to setActiveStore(SecretStore, Purpose) to make the change.

      Type Parameters:
      T - the type of secrets required by this purpose.
      Parameters:
      purposes - the purpose(s) to change the active store for.
      store - the new secret store to make active for this purpose.
      Returns:
      the updated secrets provider object.

    • setActiveStore

      protected <T extends Secret> void setActiveStore(SecretStore<? super T> store, Purpose<? extends T> purpose)
      Sets the active store to use for the given purpose. All existing stores for that purpose will be deactivated and will only be used to serve requests for existing keys that are still valid rather than to produce new active keys.
      Type Parameters:
      T - the type of secrets required by this purpose.
      Parameters:
      purpose - the purpose(s) to change the active store for.
      store - the new secret store to make active for this purpose.

    • setDefaultStores

      public SecretsProvider setDefaultStores(SecretStore<?> activeStore, SecretStore<?>... defaultStores)
      Sets the default store(s) to use if there is no specific store configured for a particular purpose.
      Parameters:
      activeStore - the store to use for all requests for active secrets.
      defaultStores - remaining valid stores to consult for existing named/valid secrets.
      Returns:
      the updated secrets provider object.

    • getActiveSecret

      public <S extends Secret> Promise<S,NoSuchSecretException> getActiveSecret(Purpose<S> purpose)
      Gets the currently active secret for the given purpose. If more than one secret exists for this purpose, then this method returns the secret that is currently active and should be used for new operations. The returned secret is guaranteed to be within the valid periods specified by its validFrom and expiry times. If no valid secret is configured for the purpose then a NoSuchSecretException is thrown instead.

      The active secret is found by first consulting the currently active store for the purpose label. If no active stores exist for the purpose, all default stores are consulted, and the first matching secret is used.

      Type Parameters:
      S - the type of secret to return.
      Parameters:
      purpose - the purpose for which the secret is intended to be used.
      Returns:
      A promise containing either the active secret for this purpose, or a NoSuchSecretException if one cannot be found.

    • getNamedSecret

      public <S extends Secret> Promise<S,NoSuchSecretException> getNamedSecret(Purpose<S> purpose, String id)
      Gets the secret for the given purpose with the given stable secret id.
      Type Parameters:
      S - the type of secret to return
      Parameters:
      purpose - the purpose for which the secret is intended to be used.
      id - the stable id of the particular secret to get.
      Returns:
      the secret with that id, or an empty result if no such secret exists.
      See Also:

    • getValidSecrets

      public <S extends Secret> Promise<Stream<S>,NeverThrowsException> getValidSecrets(Purpose<S> purpose)
      Returns all secrets for the given purpose which have not yet expired. This can be used, for instance, to get a list of all signature validation keys that are still trusted. The secrets will be returned in the order of preference of the store they are from: secrets from the active store will be first, then the most recent previous active store, and so on.
      Type Parameters:
      S - the type of secret to return.
      Parameters:
      purpose - the purpose for which the secrets are intended for.
      Returns:
      a stream of all valid secrets for the given purpose, or an empty stream if not configured.

    • getNamedOrValidSecrets

      public <S extends Secret> Promise<Stream<S>,NeverThrowsException> getNamedOrValidSecrets(Purpose<S> purpose, String id)
      If the given id is not null, then this returns the single named secret that corresponds to that stable id (or a stream of valid secrets for the given purpose if no such secret exists), otherwise it returns all valid secrets for the given purpose. This is a convenience method for a frequent case where you want to process an incoming message (e.g., to decrypt or verify it) and the message may or may not have a secret/key identifier.

      For example, to verify a JSON Web Token that might have a "kid" claim, we can do: 

      
  SignedJwt jwt = ...;
  secrets.getNamedOrValidSecrets(Purpose.VERIFY, jwt.getHeader().getKeyId())
      .map(rethrowFunction(key -> signingManager.newVerificationHandler(key)))
      .anyMatch(jwt::verify);
      Type Parameters:
      S - the type of secrets to return.
      Parameters:
      purpose - the purpose for which the secrets are intended.
      id - the optional stable id of the secret, or null if not known.
      Returns:
      a stream of all secrets to try, or an empty stream if none are applicable.

    • createActiveReference

      public <S extends Secret> SecretReference<S> createActiveReference(Purpose<S> purpose)
      Creates the secret reference from the given purpose.
      Type Parameters:
      S - The type of the SecretReference to return.
      Parameters:
      purpose - the purpose for which a secret is required.
      Returns:
      A SecretReference of the given Purpose.

    • createNamedReference

      public <S extends Secret> SecretReference<S> createNamedReference(Purpose<S> purpose, String name)
      Creates a reference to a secret with the given name (stable id) for the given purpose.
      Type Parameters:
      S - the type of secret.
      Parameters:
      purpose - the purpose.
      name - the name (stable id) of the secret.
      Returns:
      a reference to the named secret in this secrets provider.

    • createValidReference

      public <S extends Secret> ValidSecretsReference<S,NeverThrowsException> createValidReference(Purpose<S> purpose)
      Creates the valid secrets reference from the given purpose.
      Type Parameters:
      S - the type of the secrets to return.
      Parameters:
      purpose - the purpose for which a secret is required.
      Returns:
      a ValidSecretsReference of the given Purpose.

    • createValidOrNamedReference

      public <S extends Secret> ValidSecretsReference<S,NeverThrowsException> createValidOrNamedReference(Purpose<S> purpose, String name)
      Creates the valid secrets reference from the given purpose.
      Type Parameters:
      S - the type of the secrets to return.
      Parameters:
      purpose - the purpose for which a secret is required.
      name - the stableId of the secret, or null if not known.
      Returns:
      a ValidSecretsReference of the given Purpose.

    • asKeyStore

      public <T extends CryptoKey> KeyStore asKeyStore(Purpose<T> purpose)
      Returns a view of this secrets provider as a keystore for the given purpose. The keystore view will
      Type Parameters:
      T - the type of keys.
      Parameters:
      purpose - the purpose that the keystore will be used for.
      Returns:
      the keystore view of this secrets provider.

    • asKeyStore

      public KeyStore asKeyStore(Set<Purpose<? extends CryptoKey>> purposes)
      Returns a view of this secrets provider as a keystore for the given purposes. The keystore view will
      Parameters:
      purposes - the purposes that the keystore will be used for.
      Returns:
      the keystore view of this secrets provider.

    • getKeyManager

      public X509ExtendedKeyManager getKeyManager(Purpose<? extends CryptoKey> purpose)
      Returns a KeyManager that can be used to initialize an SSLContext, allowing certificates and private keys to be retrieved from this secrets provider.
      Parameters:
      purpose - the purpose to use for retrieving TLS certificates and keys.
      Returns:
      a KeyManager that obtains keys and certificates from this secrets provider.

    • getKeyManager

      public X509ExtendedKeyManager getKeyManager(Set<Purpose<? extends CryptoKey>> purposes, Options options)
      Returns a KeyManager that can be used to initialize an SSLContext, allowing certificates and private keys to be retrieved from this secrets provider.
      Parameters:
      purposes - the purposes to use for retrieving TLS certificates and keys.
      options - the options to configure the key manager. See SecretsKeyManager.KEY_MANAGER_ALGORITHM.
      Returns:
      a KeyManager that obtains keys and certificates from this secrets provider.

    • getKeyManager

      public X509ExtendedKeyManager getKeyManager(Purpose<? extends CryptoKey> purpose, Options options)
      Returns a KeyManager that can be used to initialize an SSLContext, allowing certificates and private keys to be retrieved from this secrets provider.
      Parameters:
      purpose - the purpose to use for retrieving TLS certificates and keys.
      options - the options to configure the key manager. See SecretsKeyManager.KEY_MANAGER_ALGORITHM.
      Returns:
      a KeyManager that obtains keys and certificates from this secrets provider.

    • getTrustManager

      public SecretsTrustManager getTrustManager(Purpose<? extends CryptoKey> purpose, Options options)
      Constructs an X509ExtendedTrustManager that will retrieve certificates from this secrets provider for the provided purpose. This can be used to configured SSL connections via SSLContext.init(KeyManager[], TrustManager[], SecureRandom).
      Parameters:
      purpose - the purpose to use to lookup trusted certificates.
      options - the trust manager options - see SecretsTrustManager for details.
      Returns:
      the trust manager to use

    • getTrustManager

      public SecretsTrustManager getTrustManager(Set<Purpose<? extends CryptoKey>> purposes, Options options)
      Constructs an X509ExtendedTrustManager that will retrieve certificates from this secrets provider for the provided purposes. This can be used to configured SSL connections via SSLContext.init(KeyManager[], TrustManager[], SecureRandom).
      Parameters:
      purposes - the purposes to use to lookup trusted certificates.
      options - the trust manager options - see SecretsTrustManager for details.
      Returns:
      the trust manager to use

    • getTrustManager

      public SecretsTrustManager getTrustManager(Purpose<? extends CryptoKey> purpose)
      Constructs an X509ExtendedTrustManager that will retrieve certificates from this secrets provider for the provided purpose. This can be used to configured SSL connections via SSLContext.init(KeyManager[], TrustManager[], SecureRandom). Default options will be used to configure the trust manager.
      Parameters:
      purpose - the purpose to use to lookup trusted certificates.
      Returns:
      the trust manager to use

    • useSpecificSecretForPurpose

      public <S extends Secret> SecretsProvider useSpecificSecretForPurpose(Purpose<S> purpose, S secret)
      Configures this SecretsProvider to always return the specific given secret for the given purpose. This removes any other secret stores configured for this purpose and configures the provider to only ever return this specific secret as the active and only valid secret for this purpose, until the secret expires or is manually reconfigured.
      Type Parameters:
      S - the type of secret.
      Parameters:
      purpose - the purpose to configure the secret for.
      secret - the specific secret to use for this purpose.
      Returns:
      this provider after updating the configuration.

    • useSpecificSecretsForPurpose

      public <S extends Secret> SecretsProvider useSpecificSecretsForPurpose(Purpose<S> purpose, List<S> secrets)
      Configures this SecretsProvider to always return the specific given secrets for the given purpose. This removes any other secret stores configured for this purpose and configures the provider to only ever return these specific secrets as the valid secrets for this purpose, until the secret expires or is manually reconfigured. The first secret in the list will be returned as the active secret.
      Type Parameters:
      S - the type of secrets.
      Parameters:
      purpose - the purpose to configure the secret for.
      secrets - the specific secrets to use for this purpose.
      Returns:
      this provider after updating the configuration.