org.forgerock.openig.secrets

Interface SecretsService

All Known Implementing Classes:

DefaultSecretsService

public interface SecretsService

Interface for the SecretsService.

Method Summary

Modifier and Type	Method and Description
<S extends Secret> SecretReference<S>	createReference(Purpose<S> purpose) Create a SecretReference for the given Purpose.
<S extends Secret> Promise<S,NoSuchSecretException>	getActiveSecret(Purpose<S> purpose) Gets the currently active secret for the given purpose.
<S extends Secret> Promise<S,NoSuchSecretException>	getNamedSecret(Purpose<S> purpose, String id) Gets the secret for the given purpose with the given stable secret id.
<S extends Secret> Promise<Stream<S>,NeverThrowsException>	getValidSecrets(Purpose<S> purpose) Returns all secrets for the given purpose which have not yet expired.

Method Detail

getActiveSecret

<S extends Secret> Promise<S,NoSuchSecretException> getActiveSecret(Purpose<S> purpose)

Gets the currently active secret for the given purpose. If more than one secret exists for this purpose, then this method returns the secret that is currently active and should be used for new operations. The returned secret is guaranteed to be within the valid periods specified by its validFrom and expiry times. If no valid secret is configured for the purpose then a NoSuchSecretException is thrown instead.

The active secret is found by first consulting the currently active store for the purpose label. If no active stores exist for the purpose, all default stores are consulted, and the first matching secret is used.

This method is usually used for encryption and signature operations, where you need to use the active (not rotated) crypto material.

Type Parameters:

S - the type of secret to return.

Parameters:

purpose - the purpose for which the secret is intended to be used.

Returns:

A promise containing either the active secret for this purpose, or a NoSuchSecretException if one cannot be found.

getNamedSecret

<S extends Secret> Promise<S,NoSuchSecretException> getNamedSecret(Purpose<S> purpose,
                                                                   String id)

Gets the secret for the given purpose with the given stable secret id.

This method is usually used for decryption and signature verification operations, where you may have a hint for selecting the crypto material to use for the operation. Because the verified signature may have been generated with a rotated secret (at time of verification), #getActiveSecret cannot be used.

Type Parameters:

S - the type of secret to return

Parameters:

purpose - the purpose for which the secret is intended to be used.

id - the stable id of the particular secret to get.

Returns:

the secret with that id, or an empty result if no such secret exists.

See Also:

Secret.getStableId()

getValidSecrets

<S extends Secret> Promise<Stream<S>,NeverThrowsException> getValidSecrets(Purpose<S> purpose)

Returns all secrets for the given purpose which have not yet expired. This can be used, for instance, to get a list of all signature validation keys that are still trusted. The secrets will be returned in the order of preference of the store they are from: secrets from the active store will be first, then the most recent previously active store, and so on.

Type Parameters:

S - the type of secret to return.

Parameters:

purpose - the purpose for which the secrets are intended for.

Returns:

a stream of all valid secrets for the given purpose, or an empty stream if not configured.

createReference

<S extends Secret> SecretReference<S> createReference(Purpose<S> purpose)

Create a SecretReference for the given Purpose.

Type Parameters:

S - The type of the SecretReference to return.

Parameters:

purpose - The Purpose for the SecretReference.

Returns:

A SecretReference of the given Purpose.