Package org.forgerock.secrets

Interface SecretStore<T extends Secret>

  • Type Parameters:
    T - the type of secrets that this backend can store.
    All Known Implementing Classes:
    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.

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

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

    • 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

        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.