Package org.forgerock.secrets

Class GenericSecret

java.lang.Object

org.forgerock.secrets.Secret

org.forgerock.secrets.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 Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
static GenericSecret	password(char[] password)	A helper utility for constructing a Generic Secret from a password that never expires.
static GenericSecret	password(String id, char[] password)	A helper utility for constructing a Generic Secret from a password that never expires.
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	revealAsText(Charset charset, Function<char[],T,E> function)	Reveals the secret temporarily as characters in the given character set.
<T, E extends Exception> T	revealAsUtf8(Function<char[],T,E> function)	Reveals the secret temporarily as characters in UTF-8.

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

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.

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.