org.forgerock.secrets

Class SecretBuilder

java.lang.Object

org.forgerock.secrets.SecretBuilder

public class SecretBuilder
extends Object

Provides a uniform way for secrets providers to construct secrets and keys. All Secret subtypes should supply a one-argument constructor that takes an instance of this class. Secrets providers can then supply all relevant secret material and individual types of secrets can request the material that they need. For instance, a signature verification key would request only a public key, while the signing key would request the corresponding private key.

Constructor Summary

Constructors

Constructor and Description
SecretBuilder()

Method Summary

Modifier and Type	Method and Description
SecretBuilder	allowedAlgorithms(Collection<String> allowedAlgorithms) Sets the cryptographic algorithms that can be used with this key.
SecretBuilder	allowedAlgorithms(Predicate<String> allowedAlgorithmsTest) Sets the cryptographic algorithms that can be used with this key.
<T extends Secret> T	build(Class<T> secretType) Builds a secret of the given type.
SecretBuilder	certificate(Certificate certificate) Sets the certificate associated with this secret.
SecretBuilder	clock(Clock clock) Set the source of time for the default (relative) secret expiry time.
SecretBuilder	expiresAt(Instant expiry) Sets the secret to expire at the given time.
SecretBuilder	expiresIn(long deadline, TemporalUnit unit, Clock clock) Sets the secret to expire in deadline units from now.
Predicate<String>	getAllowedAlgorithms() Returns a predicate that can be used to test whether a given algorithm can be used with this key.
Set<KeyUsage>	getAllowedKeyUsages() The allowed key usages of this key.
Certificate	getCertificate() Returns the certificate associated with this secret, or null if not available.
Instant	getExpiry() Returns the expiry time for this secret.
Provider	getProvider() Returns the security provider associated with this secret, or null if not specified.
PublicKey	getPublicKey() Returns the public key associated with this secret, or null if not available.
byte[]	getRawData() Returns the raw secret data, or null if the raw data is not available.
Key	getSecretKey() Returns the secret (or private) key associated with this secret, or null if not specified.
String	getStableId() Returns the stable id for this secret..
SecretBuilder	keyUsages(Set<KeyUsage> keyUsages) Sets the allowed key usages for this key.
SecretBuilder	password(char[] password) Sets the raw data of this secret object to the UTF-8 bytes of the given password.
SecretBuilder	publicKey(PublicKey key) Sets the public key associated with this secret.
SecretBuilder	rawData(byte[] rawData) Sets the raw data of the secret object.
SecretBuilder	secretKey(Key key) Sets the secret key for this object.
SecretBuilder	stableId(String id) Sets the stable id of this secret.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

SecretBuilder

public SecretBuilder()

Method Detail

clock

public SecretBuilder clock(Clock clock)

Set the source of time for the default (relative) secret expiry time.

Parameters:

clock - The clock to use for obtaining expiry time.

Returns:

This builder.

stableId

public SecretBuilder stableId(String id)

Sets the stable id of this secret.

Parameters:

id - the stable id of the secret.

Returns:

this builder object.

expiresAt

public SecretBuilder expiresAt(Instant expiry)

Sets the secret to expire at the given time.

Parameters:

expiry - the expiry time of the secret.

Returns:

this builder object.

expiresIn

public SecretBuilder expiresIn(long deadline,
                               TemporalUnit unit,
                               Clock clock)

Sets the secret to expire in deadline units from now.

Parameters:

deadline - the amount of time that this secret should be valid for.

unit - the units of the deadline.

clock - The clock to use for obtaining the expiry time.

Returns:

this builder object.

password

public SecretBuilder password(char[] password)

Sets the raw data of this secret object to the UTF-8 bytes of the given password.

Parameters:

password - the password.

Returns:

this builder object.

rawData

public SecretBuilder rawData(byte[] rawData)

Sets the raw data of the secret object. Typically only used for GenericSecrets.

Parameters:

rawData - the raw secret data.

Returns:

this builder object.

secretKey

public SecretBuilder secretKey(Key key)

Sets the secret key for this object. This may be either a symmetric secret key or an asymmetric private key.

Parameters:

key - the key object.

Returns:

this builder object.

publicKey

public SecretBuilder publicKey(PublicKey key)

Sets the public key associated with this secret.

Parameters:

key - the public key.

Returns:

this builder object.

certificate

public SecretBuilder certificate(Certificate certificate)

Sets the certificate associated with this secret.

Parameters:

certificate - the certificate.

Returns:

this builder object.

keyUsages

public SecretBuilder keyUsages(Set<KeyUsage> keyUsages)

Sets the allowed key usages for this key.

Parameters:

keyUsages - the allowed key usages.

Returns:

this builder object.

allowedAlgorithms

public SecretBuilder allowedAlgorithms(Predicate<String> allowedAlgorithmsTest)

Sets the cryptographic algorithms that can be used with this key. The format and processing of algorithm names is unspecified.

Parameters:

allowedAlgorithmsTest - a predicate to test whether a given algorithm is allowed to be used with this key.

Returns:

this builder object.

allowedAlgorithms

public SecretBuilder allowedAlgorithms(Collection<String> allowedAlgorithms)

Sets the cryptographic algorithms that can be used with this key. The format and processing of algorithm names is unspecified. Algorithms will be tested by calling the Collection.contains(Object) method on the supplied collection, so a case-insensitive comparison can be used by specifying a case-insensitive collection. It is recommended to use a case-insensitive collection unless case-sensitivity is mandatory for a particular set of algorithms. The collection is not copied, so the passed collection should not be modified after calling this method.

It is recommended that this is populated with at least the following algorithm names as a default:

• The Java Cryptography Architecture/Extensions standard name, such as SHA256WithRSA or AES/GCM/NoPadding
• The JOSE/WebCrypto name, such as ES256 or A256KW. Note: in the case of JWE with a symmetric key that is intended for direct encryption (alg=dir it is recommended to also include the names of the relevant enc content encryption algorithms the key is intended to be used with, such as A256GCM or A128CBC-HS256.

Parameters:

allowedAlgorithms - the set of allowed algorithms that can be used with this key.

Returns:

this builder object.

getAllowedKeyUsages

public Set<KeyUsage> getAllowedKeyUsages()

The allowed key usages of this key.

Returns:

the allowed key uses of this key.

getAllowedAlgorithms

public Predicate<String> getAllowedAlgorithms()

Returns a predicate that can be used to test whether a given algorithm can be used with this key. The default predicate always returns true for any input.

Returns:

the allowed algorithms predicate.

getStableId

public String getStableId()

Returns the stable id for this secret..

Returns:

the stable id for this secret.

getExpiry

public Instant getExpiry()

Returns the expiry time for this secret.

Returns:

the expiry time for this secret.

getRawData

public byte[] getRawData()
                  throws NoSuchSecretException

Returns the raw secret data, or null if the raw data is not available.

Returns:

the raw secret data, or null if the raw data is not available.

Throws:

NoSuchSecretException - if the raw secret cannot be extracted.

getSecretKey

public Key getSecretKey()
                 throws NoSuchSecretException

Returns the secret (or private) key associated with this secret, or null if not specified.

Returns:

the secret (or private) key associated with this secret, or null if not specified.

Throws:

NoSuchSecretException - if the secret cannot be extracted.

getPublicKey

public PublicKey getPublicKey()

Returns the public key associated with this secret, or null if not available.

Returns:

the public key associated with this secret, or null if not available.

getProvider

public Provider getProvider()

Returns the security provider associated with this secret, or null if not specified.

Returns:

the security provider associated with this secret, or null if not specified.

getCertificate

public Certificate getCertificate()

Returns the certificate associated with this secret, or null if not available.

Returns:

the certificate associated with this secret, or null if not available.

build

public <T extends Secret> T build(Class<T> secretType)
                           throws NoSuchSecretException

Builds a secret of the given type.

Type Parameters:

T - the type of secret to build.

Parameters:

secretType - the type of secret to build.

Returns:

the constructed secret object.

Throws:

NoSuchSecretException - If the secret could not be built, or one of the secrets used to unlock this secret could not be obtained.