Package org.forgerock.openig.secrets

Class SecretsUtils

java.lang.Object

org.forgerock.openig.secrets.SecretsUtils

public final class SecretsUtils
extends Object

Utility class to use the Commons Secret API.

Since:

6.5

Method Summary

Modifier and Type	Method	Description
static Key	exportAsKey(CryptoKey cryptoKey)	Exports the key material in the raw format.
static Key	exportAsKeyAndClose(CryptoKey cryptoKey)	Exports the key material in the raw format and close the provided key material.
static byte[]	getPasswordSecretIdOrPasswordAsByte(SecretsProvider secretsProvider, JsonValue secretIdNode, JsonValue deprecatedNode, org.slf4j.Logger logger)	Retrieve a required shared secret value (as byte[]) from the given secretIdNode and deprecatedNode nodes.
static SecretsProvider	getSecretsProviderOrSecretsService(org.slf4j.Logger logger, JsonValue node, Heap heap)	Returns a SecretsProvider as specified with the secretsProvider attribute or falling back to a new SecretsProvider wrapping the SecretsService found in the heap.
static <S extends CryptoKey> S	retrieveCryptoKeyFromSecretId(SecretsProvider secretsProvider, JsonValue secretIdNode, Class<S> type)	Retrieves a CryptoKey from the given node.
static <S extends CryptoKey> Key	retrieveKeyFromSecretId(SecretsProvider secretsProvider, JsonValue secretIdNode, Class<S> type)	Retrieves a Key from the given node.
static SecretReference<GenericSecret>	retrievePasswordAsReference(SecretsProvider secretsProvider, JsonValue secretIdNode, JsonValue deprecatedNode, org.slf4j.Logger logger)	Retrieve a required password as a SecretReference from the given secretIdNode and deprecatedNode nodes.
static SecretReference<GenericSecret>	retrievePasswordAsReference(SecretsProvider secretsProvider, JsonValue secretIdNode, JsonValue deprecatedNode, org.slf4j.Logger logger, boolean isRequired)	Retrieve a password as a SecretReference from the given secretIdNode and deprecatedNode nodes.

Methods inherited from class java.lang.Object

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

Method Detail

getPasswordSecretIdOrPasswordAsByte

public static byte[] getPasswordSecretIdOrPasswordAsByte(SecretsProvider secretsProvider,
                                                         JsonValue secretIdNode,
                                                         JsonValue deprecatedNode,
                                                         org.slf4j.Logger logger)
                                                  throws NoSuchSecretException

Retrieve a required shared secret value (as byte[]) from the given secretIdNode and deprecatedNode nodes.

• Shared secret referenced from the secretIdNode node has precedence.
• When secret reference is provided but secret not found, a NoSuchSecretException is thrown
• When secret reference is not used, Base64 decoded value (from deprecatedNode) is returned
• If value is missing, an exception is thrown

This method logs deprecation warnings if shared secret is resolved from the deprecatedNode node value.

Parameters:

secretsProvider - The SecretsProvider used to retrieve the secret.

secretIdNode - The node describing the Purpose where the password will be available.

deprecatedNode - The deprecated node holding the password. Deprecated since 6.5.

logger - The logger used to display warnings and other deprecation messages.

Returns:

The String representing the password.

Throws:

NoSuchSecretException - If secret reference cannot be resolved.

retrieveKeyFromSecretId

public static <S extends CryptoKey> Key retrieveKeyFromSecretId(SecretsProvider secretsProvider,
                                                                JsonValue secretIdNode,
                                                                Class<S> type)
                                                         throws NoSuchSecretException

Retrieves a Key from the given node.

Type Parameters:

S - The type of the secret.

Parameters:

secretsProvider - The SecretsProvider used to retrieve the secret.

secretIdNode - The secretId node.

type - The expected type of the secret.

Returns:

Key if the secret is found.

Throws:

NoSuchSecretException - If there is no corresponding key.

exportAsKey

public static Key exportAsKey(CryptoKey cryptoKey)
                       throws NoSuchSecretException

Exports the key material in the raw format.

Parameters:

cryptoKey - The key material to export

Returns:

the exported key material.

Throws:

NoSuchSecretException - if the secret could not be exported.

exportAsKeyAndClose

public static Key exportAsKeyAndClose(CryptoKey cryptoKey)
                               throws NoSuchSecretException

Exports the key material in the raw format and close the provided key material.

Parameters:

cryptoKey - The key material to export

Returns:

the exported key material.

Throws:

NoSuchSecretException - if the secret could not be exported.

retrieveCryptoKeyFromSecretId

public static <S extends CryptoKey> S retrieveCryptoKeyFromSecretId(SecretsProvider secretsProvider,
                                                                    JsonValue secretIdNode,
                                                                    Class<S> type)
                                                             throws NoSuchSecretException

Retrieves a CryptoKey from the given node.

Type Parameters:

S - The type of the secret.

Parameters:

secretsProvider - The SecretsProvider used to retrieve the secret.

secretIdNode - The secretId node.

type - The expected type of the secret.

Returns:

CryptoKey if the secret is found.

Throws:

NoSuchSecretException - If there is no corresponding key.

getSecretsProviderOrSecretsService

public static SecretsProvider getSecretsProviderOrSecretsService(org.slf4j.Logger logger,
                                                                 JsonValue node,
                                                                 Heap heap)
                                                          throws HeapException

Returns a SecretsProvider as specified with the secretsProvider attribute or falling back to a new SecretsProvider wrapping the SecretsService found in the heap.

Not using the new attribute triggers a deprecation warning.

Not using secretsProvider has been deprecated in 7.0.0.

Parameters:

logger - Used for logging deprecation warnings (if any)

node - JsonValue containing secretsProvider attribute

heap - heap for objects retrieval

Returns:

a SecretsProvider

Throws:

HeapException - if provider cannot be created/found in the heap

retrievePasswordAsReference

public static SecretReference<GenericSecret> retrievePasswordAsReference(SecretsProvider secretsProvider,
                                                                         JsonValue secretIdNode,
                                                                         JsonValue deprecatedNode,
                                                                         org.slf4j.Logger logger)

Retrieve a required password as a SecretReference from the given secretIdNode and deprecatedNode nodes.

• Password referenced from the secretIdNode node has precedence.
• When secret reference is provided but secret not found, a NoSuchSecretException is thrown
• When secret reference is not used, direct password value (from deprecatedNode) is returned
• If value is missing, an exception is thrown

This method logs deprecation warnings if password is resolved from the deprecatedNode node value.

Parameters:

secretsProvider - The SecretsProvider used to retrieve the secret.

secretIdNode - The node describing the Purpose where the password will be available.

deprecatedNode - The deprecated node holding the password. Deprecated since 6.5.

logger - The logger used to display warnings and other deprecation messages.

Returns:

The SecretReference to this password.

retrievePasswordAsReference

public static SecretReference<GenericSecret> retrievePasswordAsReference(SecretsProvider secretsProvider,
                                                                         JsonValue secretIdNode,
                                                                         JsonValue deprecatedNode,
                                                                         org.slf4j.Logger logger,
                                                                         boolean isRequired)

Retrieve a password as a SecretReference from the given secretIdNode and deprecatedNode nodes.

• Password referenced from the secretIdNode node has precedence.
• When secret reference is provided but secret not found, a NoSuchSecretException is thrown
• When secret reference is not used, direct password value (from deprecatedNode) is returned
• If value is missing, an exception is thrown

This method logs deprecation warnings if password is resolved from the deprecatedNode node value.

Parameters:

secretsProvider - The SecretsProvider used to retrieve the secret.

secretIdNode - The node describing the Purpose where the password will be available.

deprecatedNode - The deprecated node holding the password. Deprecated since 6.5.

logger - The logger used to display warnings and other deprecation messages.

isRequired - If set to true, this method will throw an exception if deprecatedNode has a null value.

Returns:

The SecretReference to this password.