Package org.forgerock.secrets

Class GenericSecret

java.lang.Object
org.forgerock.secrets.Secret
org.forgerock.secrets.GenericSecret
All Implemented Interfaces:
AutoCloseable, Destroyable
public final class GenericSecret extends Secret implements AutoCloseable, Destroyable
A generic secret represented as an opaque blob of bytes, such as a password or API key. Secret data is held in an off-heap byte buffer where supported, and is encrypted using a random key. These protections provide best-effort obfuscation against heap dump inspection. Secrets should be held in memory for as short a time as possible and the destroy() method called when no longer required.

  • Constructor Details

    • GenericSecret

      public GenericSecret(SecretBuilder builder) throws NoSuchSecretException
      Constructs a generic secret with the given stable identifier and secret data.
      Parameters:
      builder - the secret builder.
      Throws:
      NoSuchSecretException - if the secret could not be constructed from the builder.

  • Method Details

    • password

      public static GenericSecret password(String id, char[] password, Clock clock)
      A helper utility for constructing a Generic Secret from a password with a default expiry time. This will take a copy of the password, so the password argument can safely be wiped after this call returns.
      Parameters:
      id - the stable id of the password.
      password - the password.
      clock - The clock to use for expiry time.
      Returns:
      a generic secret that wraps the given password.

    • password

      public static GenericSecret password(char[] password)
      A helper utility for constructing a Generic Secret from a password that never expires. This will take a copy of the password, so the password argument can safely be wiped after this call returns. A random stable id will be assigned.
      Parameters:
      password - the password.
      Returns:
      a generic secret that wraps the given password.

    • password

      public static GenericSecret password(String id, char[] password)
      A helper utility for constructing a Generic Secret from a password that never expires. This will take a copy of the password, so the password argument can safely be wiped after this call returns.
      Parameters:
      id - the stable id of the password.
      password - the password.
      Returns:
      a generic secret that wraps the given password.

    • reveal

      public <T, E extends Exception> T reveal(Function<byte[],T,E> function) throws E
      Reveals the secret temporarily, allowing it to be used for its intended purpose. Note that the consumer should not make any assumptions about the availability of the secret bytes after the function returns. They may be overwritten or destroyed, so the consumer should make a defensive copy if they need to retain the secret material beyond the lifetime of this call. The GenericSecret object is not destroyed by this method and so can be reused. Use revealAndDestroy(Function) to also destroy the GenericSecret itself after the method completes.
      Type Parameters:
      T - the type of object returned by the consumer.
      E - the type of exceptions thrown by the consumer.
      Parameters:
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      Throws:
      E - if the consumer throws.

    • revealAndDestroy

      public <T, E extends Exception> T revealAndDestroy(Function<byte[],T,E> function) throws E
      Reveals the secret temporarily and then scrubs the secret material from memory. See reveal(Function).
      Type Parameters:
      T - the type of object returned by the consumer.
      E - the type of exceptions thrown by the consumer.
      Parameters:
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      Throws:
      E - if the consumer throws.

    • revealAsText

      public <T, E extends Exception> T revealAsText(Charset charset, Function<char[],T,E> function) throws E
      Reveals the secret temporarily as characters in the given character set. Any bytes that cannot be interpreted in the given character set will be replaced with the charset's replacement character. Note that the consumer should not make any assumptions about the availability of the secret characters after the function returns. They may be overwritten or destroyed, so the consumer should make a defensive copy if they need to retain the secret beyond the lifetime of this call.
      Type Parameters:
      T - the type of object returned by the consumer.
      E - the type of exceptions thrown by the consumer.
      Parameters:
      charset - the character set to interpret the secret as.
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      Throws:
      E - if the consumer throws.

    • revealAsTextAndDestroy

      public <T, E extends Exception> T revealAsTextAndDestroy(Charset charset, Function<char[],T,E> function) throws E
      Reveals the secret temporarily as characters in the given character set and then scrubs the secret material from memory. See revealAsText(Charset, Function).
      Type Parameters:
      T - the type of object returned by the consumer.
      E - the type of exceptions thrown by the consumer.
      Parameters:
      charset - the character set to interpret the secret as.
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      Throws:
      E - if the consumer throws.

    • revealAsUtf8

      public <T, E extends Exception> T revealAsUtf8(Function<char[],T,E> function) throws E
      Reveals the secret temporarily as characters in UTF-8. Any bytes that cannot be interpreted as UTF-8 will be replaced with the replacement character. Note that the consumer should not make any assumptions about the availability of the secret characters after the function returns. They may be overwritten or destroyed, so the consumer should make a defensive copy if they need to retain the secret beyond the lifetime of this call.
      Type Parameters:
      T - the type of object returned by the consumer.
      E - the type of exceptions thrown by the consumer.
      Parameters:
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      Throws:
      E - if the consumer throws.

    • revealAsUtf8AndDestroy

      public <T, E extends Exception> T revealAsUtf8AndDestroy(Function<char[],T,E> function) throws E
      Reveals the secret temporarily as characters in UTF-8 and then scrubs the secret from memory. See revealAsUtf8(Function).
      Type Parameters:
      T - the type of object returned by the consumer.
      E - the type of exceptions thrown by the consumer.
      Parameters:
      function - the consumer function to reveal the secret to.
      Returns:
      the result of the consumer function.
      Throws:
      E - if the consumer throws.

    • close

      public void close()
      Scrubs the secret value from memory on a best-effort basis.
      Specified by:
      close in interface AutoCloseable
      Overrides:
      close in class Secret

    • isClosed

      public boolean isClosed()
      Description copied from class: Secret
      Indicates whether this secret has been closed by calling the Secret.close() method. A secret that has been closed should be considered invalid and re-fetched from the SecretsProvider.
      Overrides:
      isClosed in class Secret
      Returns:
      true if the secret has been closed.

    • destroy

      public void destroy()
      Specified by:
      destroy in interface Destroyable

    • isDestroyed

      public boolean isDestroyed()
      Specified by:
      isDestroyed in interface Destroyable