public class VaultException

The failure every vault and protected-storage operation reports, carrying a VaultError rather than only a message.

Extends CryptoException so existing catch (CryptoException) around Cipher work keeps compiling and keeps catching. Branch on getError() rather than on the message.

The message carries no secret

Redaction happens where the exception is constructed rather than where it is read, because a message reaches logs, crash reports and telemetry before anybody chooses to look at it. The rule for anyone adding a throw site: the account name is allowed, the value is not, and neither is a length or a prefix of it.

Constructors

`public VaultException(VaultError error, String message)`
`public VaultException(VaultError error, String message, Throwable cause)`
`public VaultException(VaultError error, String message, Protection unmetProtection, Throwable cause)`	The constructor for `VaultError.POLICY_NOT_MET`, which is the one failure that can name what was missing.

Methods

`public` `VaultError getError()`	The code to branch on.
`public` `Protection getUnmetProtection()`	For `VaultError.POLICY_NOT_MET`, the protection that was required and not provided.
`public boolean isDefinitelyAbsent()`	Whether this failure means the entry is definitely absent, which is the only state in which generating a replacement key is safe.

Inherited methods

From Throwable

initCause, getCause, getMessage, printStackTrace, printStackTrace, toString, addSuppressed, getStackTrace, setStackTrace, getSuppressed, getLocalizedMessage

From Object

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

Constructor details

VaultException

public VaultException(VaultError error, String message)

Parameters

error VaultError: the code callers branch on, null becomes VaultError.UNKNOWN
message String: description for a human. Must not contain a secret, an account value or a fragment of ciphertext: this string reaches logs, crash reports and telemetry.

VaultException

public VaultException(VaultError error, String message, Throwable cause)

Parameters

error VaultError: the code callers branch on
message String: description for a human, carrying no secret material
cause Throwable: the underlying failure, or null

VaultException

public VaultException(VaultError error, String message, Protection unmetProtection, Throwable cause)

The constructor for VaultError.POLICY_NOT_MET, which is the one failure that can name what was missing.

Parameters

error VaultError: the code callers branch on
message String: description for a human, carrying no secret material
unmetProtection Protection: the protection that was required and not provided, or null
cause Throwable: the underlying failure, or null

Method details

getError

public VaultError getError()

The code to branch on.

getUnmetProtection

public Protection getUnmetProtection()

For VaultError.POLICY_NOT_MET, the protection that was required and not provided. Null for every other code.

isDefinitelyAbsent

public boolean isDefinitelyAbsent()

Whether this failure means the entry is definitely absent, which is the only state in which generating a replacement key is safe.

Written as a method rather than left to callers comparing codes because getting it wrong is unrecoverable: a caller that also accepts VaultError.TEMPORARILY_UNREADABLE here overwrites a key that was there and orphans everything it protected.