Package org.apache.juneau.commons.secret

Interface SecretStore

All Known Implementing Classes:

EnvVarSecretStore, InMemorySecretStore, KeychainSecretStore

public interface SecretStore

SPI for storing and retrieving a secret by key — the secure, mutable sibling of PropertySource.

Where a PropertySource is a read-only source of ordinary configuration values, a SecretStore adds write/delete plus sensitivity semantics. The SPI is deliberately narrow — it deals only in a String key and a char[] secret, with no dependency on any particular backend.

Sensitivity is intrinsic. Secret values are held as char[] rather than String so they can be explicitly zeroed and do not linger in the string pool. An implementation must never toString(), log, or otherwise dump a secret value. Callers are responsible for zeroing the arrays they pass to store(java.lang.String, char[]) and receive from find(java.lang.String) once done with them.

Three-state presence model. The three operations together model a clean present-with-value / present-without-materializing / absent distinction:

• find(String) — returns the secret value when present (Optional of char[]), or Optional.empty() when absent. This is the only method that materializes the value.
• exists(String) — reports whether a secret is stored under the key without retrieving (and, for backends that decrypt on read, without decrypting) it. Prefer this over find(java.lang.String) when only presence matters, so the secret is never pulled into memory needlessly.
• absent — find(java.lang.String) returns empty and exists(java.lang.String) returns false.

Backend-unavailable behavior is a consumer decision. The built-in InMemorySecretStore and EnvVarSecretStore never fail on a well-formed call, so they simply throw on a genuine error. Network- or OS-backed implementations (for example an OS-keychain-backed store in a separate module) should let the consumer pick fail-open vs fail-closed via a FailMode rather than baking a policy into the SPI.

See Also:

• InMemorySecretStore
• EnvVarSecretStore
• FailMode
• SecretStores

Since:

10.0.0

Method Summary

Modifier and Type	Method	Description
boolean	delete(String key)	Deletes the secret stored under the specified key.
boolean	exists(String key)	Returns whether a secret is stored under the specified key without materializing its value.
Optional<char[]>	find(String key)	Returns the secret stored under the specified key.
void	store(String key, char[] secret)	Stores a secret under the specified key, replacing any existing value.

Method Details

store

void store(String key,
 char[] secret)

Stores a secret under the specified key, replacing any existing value.

The caller retains ownership of secret and may zero it after this call returns; an implementation that needs to retain the value must copy it.

Parameters:

key - The key under which to store the secret. Must not be null.

secret - The secret value. Must not be null.

Throws:

UnsupportedOperationException - If this store is read-only.

find

Optional<char[]> find(String key)

Returns the secret stored under the specified key.

The returned array is the caller's to own and zero; it is not a live view of the store's internal state.

Parameters:

key - The key to look up. Must not be null.

Returns:

The secret value, or Optional.empty() if no secret is stored under the key.

exists

boolean exists(String key)

Returns whether a secret is stored under the specified key without materializing its value.

Parameters:

key - The key to check. Must not be null.

Returns:

true if a secret is stored under the key.

delete

boolean delete(String key)

Deletes the secret stored under the specified key.

Parameters:

key - The key to delete. Must not be null.

Returns:

true if a secret was present and removed; false if the key was already absent.

Throws:

UnsupportedOperationException - If this store is read-only.