Package org.forgerock.secrets

Interface SecretStore<T extends Secret>

Type Parameters:
T - the type of secrets that this backend can store.
All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
AccessTokenSecretStore, Base64EncodedSecretStore, FileSystemSecretStore, GenericWrapperSecretStore, JwkSetSecretStore, KeyStoreSecretStore, PropertyResolverSecretStore, ThreadPoolSecretStore
public interface SecretStore<T extends Secret> extends AutoCloseable
A backend storage mechanism for certain kinds of secrets. Unlike a SecretsProvider a store may only be capable of storing certain types of secrets.

Implementors should override the toString() method to return sensible information for debugging purposes (do not include secret material in this output).

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Option<Clock>
    CLOCK
    Specifies the clock to use when making time comparisons.
    static final 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
    Description
    default void
    close()
    Releases any resources held by this store.
    default <S extends T>
    Promise<S,NoSuchSecretException>
    getActive(Purpose<S> purpose)
    Returns the active secret for the given purpose.
    default <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 Details

    • 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
      Specifies the clock to use when making time comparisons. Defaults to Clock.systemUTC().

  • Method Details

    • close

      default void close()
      Releases any resources held by this store. Store implementations that hold system resources (e.g. network connections, thread pools) should override this method to release them. Implementations that do not hold resources may rely on this default no-op. This method declares no checked exception, narrowing the AutoCloseable contract.

      Implementations of this method might use blocking I/O.

      Specified by:
      close in interface AutoCloseable

    • 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

      default <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

      default <S extends T> Promise<S,NoSuchSecretException> getNamed(Purpose<S> purpose, String name)
      Returns the named secret from this store. The default implementation calls getValid(Purpose) and then returns the first valid key with a matching stable ID.
      Type Parameters:
      S - the type of secret.
      Parameters:
      purpose - the secret purpose.
      name - the name (stable id) of the secret.
      Returns:
      a promise for the named secret, or a NoSuchSecretException promise 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. 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.

    • 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.