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 GenericSecret.destroy() method called when no longer required.

Constructor Summary

Constructors

Constructor and Description
GenericSecret(SecretBuilder builder) Constructs a generic secret with the given stable identifier and secret data.

Method Summary

Modifier and Type	Method and Description
void	close() Scrubs the secret value from memory on a best-effort basis.
void	destroy()
boolean	isDestroyed()
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.
<T,E extends Exception> T	reveal(Function<byte[],T,E> function) Reveals the secret temporarily, allowing it to be used for its intended purpose.
<T,E extends Exception> T	revealAndDestroy(Function<byte[],T,E> function) Reveals the secret temporarily and then scrubs the secret material from memory.
<T,E extends Exception> T	revealAsText(Charset charset, Function<char[],T,E> function) Reveals the secret temporarily as characters in the given character set.
<T,E extends Exception> T	revealAsTextAndDestroy(Charset charset, Function<char[],T,E> function) Reveals the secret temporarily as characters in the given character set and then scrubs the secret material from memory.
<T,E extends Exception> T	revealAsUtf8(Function<char[],T,E> function) Reveals the secret temporarily as characters in UTF-8.
<T,E extends Exception> T	revealAsUtf8AndDestroy(Function<char[],T,E> function) Reveals the secret temporarily as characters in UTF-8 and then scrubs the secret from memory.

Methods inherited from class org.forgerock.secrets.Secret

equals, getExpiryTime, getStableId, hashCode, isExpired, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

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.

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. Use GenericSecret.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.

E extends Exception

revealAndDestroy

public <T,E extends Exception> T revealAndDestroy(Function<byte[],T,E> function)
                                           throws E extends Exception

Reveals the secret temporarily and then scrubs the secret material from memory. See GenericSecret.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.

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

revealAsTextAndDestroy

public <T,E extends Exception> T revealAsTextAndDestroy(Charset charset,
                                                        Function<char[],T,E> function)
                                                 throws E extends Exception

Reveals the secret temporarily as characters in the given character set and then scrubs the secret material from memory. See GenericSecret.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.

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

revealAsUtf8AndDestroy

public <T,E extends Exception> T revealAsUtf8AndDestroy(Function<char[],T,E> function)
                                                 throws E extends Exception

Reveals the secret temporarily as characters in UTF-8 and then scrubs the secret from memory. See GenericSecret.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.

E extends Exception

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

destroy

public void destroy()

Specified by:

destroy in interface Destroyable

isDestroyed

public boolean isDestroyed()

Specified by:

isDestroyed in interface Destroyable