com.schibsted.security.strongbox.sdk

Interface SecretsGroup

All Superinterfaces:

java.lang.AutoCloseable

public interface SecretsGroup
extends java.lang.AutoCloseable

A SecretsGroup is a logical collection of secrets. The interface does not expose how the secrets are encrypted and stored, only how to add and retrieve them. While the stream is the the most flexible way to retrieve Secrets, we recommend using the convenience methods like getActive whenever possible. The convenience methods use the concept of active. A secret entry is active if it is enabled, and now (in seconds) are larger or equal to not before (if present), and less than or equal to not after (if present).

Method Summary

Modifier and Type	Method and Description
RawSecretEntry	addVersion(NewSecretEntry newSecretEntry) Add a version to an existing version.
void	close() Certain Secret Groups, e.g.
RawSecretEntry	create(NewSecretEntry newSecretEntry) Create a new Secret.
SecretEntry	decrypt(RawSecretEntry rawSecretEntry, SecretIdentifier expectedSecretIdentifier, long expectedVersion) Decrypts a RawSecretEntry into a SecretEntry.
SecretEntry	decryptEvenIfNotActive(RawSecretEntry rawSecretEntry, SecretIdentifier expectedSecretIdentifier, long expectedVersion) Decrypts a RawSecretEntry into a SecretEntry.
void	delete(SecretIdentifier secretIdentifier) Delete all versions of the given secret.
default java.util.Optional<SecretEntry>	getActive(SecretIdentifier secretIdentifier, long targetVersion) Get a specific version of a secret.
default java.util.List<SecretEntry>	getAllActiveVersions() Get all entries that are active for all secrets.
default java.util.List<SecretEntry>	getAllActiveVersions(SecretIdentifier secretIdentifier) Get all active versions of a secret.
default java.util.Optional<SecretEntry>	getLatestActiveVersion(SecretIdentifier secretIdentifier) Convenience method to get the latest active version of a secret, i.e.
default java.util.List<SecretEntry>	getLatestActiveVersionOfAllSecrets() Get the latest active version of all secrets, i.e.
java.util.Set<SecretIdentifier>	identifiers() This method is used to list the secret identifiers in the Secret Group.
SRN	srn(SecretIdentifier secretIdentifier) Returns a globally unique identifier of the particular secret.
com.schibsted.security.strongbox.sdk.internal.kv4j.generic.frontend.KVStream<RawSecretEntry>	stream() Get a key value stream of the entries, that can be used to filter and retrieve some subset of the secrets.
RawSecretEntry	update(SecretMetadata secretMetadata) Update the metadata for a Secret.

Method Detail

create

RawSecretEntry create(NewSecretEntry newSecretEntry)

Create a new Secret. This method will throw if the secret already exists.

Parameters:

newSecretEntry - the secret entry to create

Returns:

RawSecretEntry of the newly created entry

Throws:

AlreadyExistsException - if the secret already exists

addVersion

RawSecretEntry addVersion(NewSecretEntry newSecretEntry)

Add a version to an existing version. This method will throw if the secret does not already exist. The version will automatically be incremented and throw if there is a race on the version.

Parameters:

newSecretEntry - the Secret entry to add

Returns:

RawSecretEntry of the newly created entry

Throws:

DoesNotExistException - if the secret does not exist

AlreadyExistsException - if there is a race on the automatically incremented version

update

RawSecretEntry update(SecretMetadata secretMetadata)

Update the metadata for a Secret. Optional fields that are left empty will be left unchanged.

Parameters:

secretMetadata - metadata to update

Returns:

RawSecretEntry of the updated secret entry

Throws:

DoesNotExistException - if the secret does not exist

identifiers

java.util.Set<SecretIdentifier> identifiers()

This method is used to list the secret identifiers in the Secret Group.

Returns:

The set of SecretIdentifier that are present in this Secret Group

delete

void delete(SecretIdentifier secretIdentifier)

Delete all versions of the given secret. Individual secret entries cannot be deleted. This method will succeed even if the secret does not exist.

Parameters:

secretIdentifier - the identifier of the secret to delete

stream

com.schibsted.security.strongbox.sdk.internal.kv4j.generic.frontend.KVStream<RawSecretEntry> stream()

Get a key value stream of the entries, that can be used to filter and retrieve some subset of the secrets. This is the most flexible way to retrieve secrets, and is used by all the convenience methods. We recommend that you use the convenience methods like getActive whenever possible.

Returns:

the key value stream of the RawSecretEntry for this Secret Group

decrypt

SecretEntry decrypt(RawSecretEntry rawSecretEntry,
                    SecretIdentifier expectedSecretIdentifier,
                    long expectedVersion)

Decrypts a RawSecretEntry into a SecretEntry. This includes verifying the integrity of all the returned data, both encrypted and decrypted. This method expects the secret to be active. If you do not need to verify that property, please see decryptEvenIfNotActive. Please see the top of the class for the definition of active.

Parameters:

rawSecretEntry - The RawSecretEntry to be decrypted and verified

expectedSecretIdentifier - The @{code SecretIdentifier} you are expecting to decrypt (to verify integrity)

expectedVersion - The version you are expecting to decrypt (to verify integrity)

Returns:

The decrypted SecretEntry

Throws:

PotentiallyMaliciousDataException - if the integrity cannot be verified

decryptEvenIfNotActive

SecretEntry decryptEvenIfNotActive(RawSecretEntry rawSecretEntry,
                                   SecretIdentifier expectedSecretIdentifier,
                                   long expectedVersion)

Decrypts a RawSecretEntry into a SecretEntry. This includes verifying the integrity of all the returned data, both encrypted and decrypted, but not if the secret is active. Please see the top of the class for the definition of active.

Parameters:

rawSecretEntry - The RawSecretEntry to be decrypted and verified

expectedSecretIdentifier - The @{code SecretIdentifier} you are expecting to decrypt (to verify integrity)

expectedVersion - The version you are expecting to decrypt (to verify integrity)

Returns:

The decrypted SecretEntry

Throws:

PotentiallyMaliciousDataException - if the integrity cannot be verified

srn

SRN srn(SecretIdentifier secretIdentifier)

Returns a globally unique identifier of the particular secret.

Parameters:

secretIdentifier - identifier of the secret to get SRN for

Returns:

The SRN of the given secret

getLatestActiveVersion

default java.util.Optional<SecretEntry> getLatestActiveVersion(SecretIdentifier secretIdentifier)

Convenience method to get the latest active version of a secret, i.e. the entry with the highest version number that is active. If you know which version you want, we recommend to use getActive(SecretIdentifier, long), as this offers 'pinning' of the version. Please see the top of the class for the definition of active.

Parameters:

secretIdentifier - identifier of the secret to retrieve

Returns:

the SecretEntry requested

Throws:

PotentiallyMaliciousDataException - if the integrity of the data returned is compromised

getActive

default java.util.Optional<SecretEntry> getActive(SecretIdentifier secretIdentifier,
                                                  long targetVersion)

Get a specific version of a secret. This is the most secure in that even a untrusted storage backend cannot return a different version (but otherwise legal) of the secret, without us being able to detect it. Please see the top of the class for the definition of active.

Parameters:

secretIdentifier - identifier of the secret to retrieve

targetVersion - version of the entry to retrieve

Returns:

the SecretEntry requested

Throws:

PotentiallyMaliciousDataException - if the integrity of the data returned is compromised

getAllActiveVersions

default java.util.List<SecretEntry> getAllActiveVersions(SecretIdentifier secretIdentifier)

Get all active versions of a secret. Please see the top of the class for the definition of active.

Parameters:

secretIdentifier - identifier of the secret to retrieve

Returns:

a list of SecretEntry matching the request

Throws:

PotentiallyMaliciousDataException - if the integrity of the data returned is compromised

getLatestActiveVersionOfAllSecrets

default java.util.List<SecretEntry> getLatestActiveVersionOfAllSecrets()

Get the latest active version of all secrets, i.e. for all secrets, the entry with the highest version that is active. Please see the top of the class for the definition of active.

Returns:

a list of SecretEntry matching the request

Throws:

PotentiallyMaliciousDataException - if the integrity of the data returned is compromised

getAllActiveVersions

default java.util.List<SecretEntry> getAllActiveVersions()

Get all entries that are active for all secrets. Please see the top of the class for the definition of active.

Returns:

a list of SecretEntry matching the request

Throws:

PotentiallyMaliciousDataException - if the integrity of the data returned is compromised

close

void close()

Certain Secret Groups, e.g. if backed by a file, requires the Secret Group to be closed for changes to take effect. To avoid making the user of this class be aware of the distinction, we require all implementations to be closed.

Specified by:

close in interface java.lang.AutoCloseable