Package org.forgerock.secrets

Class GenericSecret

  • public final class GenericSecret
extends Secret
    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.

    • Constructor Detail

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

      • 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 extends Exception
        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.
        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.
        E extends Exception

      • revealAsText

        public <T,​E extends Exception> T revealAsText​(Charset charset,
                                                    Function<char[],​T,​E> function)
                                             throws E extends Exception
        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.
        E extends Exception

      • revealAsUtf8

        public <T,​E extends Exception> T revealAsUtf8​(Function<char[],​T,​E> function)
                                             throws E extends Exception
        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.
        E extends Exception