Class VaultException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

com.codename1.security.CryptoException

com.codename1.security.vault.VaultException

public class VaultException
extends CryptoException

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.

Constructor Summary

Constructors

Constructor	Description
VaultException(VaultError error, String message)	Parameters
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.
VaultException(VaultError error, String message, Throwable cause)	Parameters

Method Summary

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

Methods inherited from class Throwable

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

Methods inherited from class Object

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

Constructor Details

VaultException

public VaultException(VaultError error,
 String message)

Parameters

• error: the code callers branch on, null becomes VaultError.UNKNOWN

• message: 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: the code callers branch on

• message: description for a human, carrying no secret material

• cause: 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: the code callers branch on

• message: description for a human, carrying no secret material

• unmetProtection: the protection that was required and not provided, or null

• cause: 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.