Interface Secret
This type exists because "is this value plaintext or ciphertext?" must be answerable from the
type rather than from where the value happened to come from. A configuration item read
through ConfigurationApi carries ciphertext; one the host pre-decrypted carries plaintext;
a plain String property looks identical in both cases and gives an author no way to tell.
A Secret is unambiguous: it is always encrypted at rest and only ever plaintext at the
moment you call reveal().
Revealing registers the value for masking
reveal() does two things: it decrypts, and it records the plaintext in this execution's
mask set. Everything written to the task log afterwards - TaskExecutionContext.log(String),
TaskOutput.asOutputStream(), TaskOutput.pipeFrom(java.io.Reader) - has that value
replaced with ******** on its way out, including output produced by a remote command that
echoed the secret back at you.
That is the whole reason to prefer Secret over reading a password property as a
String and decrypting it yourself: masking is a consequence of asking for the value, so it
cannot be forgotten, and it covers secrets found at any depth in a configuration graph rather than
only the ones the host happened to know about in advance.
Do not hold on to the plaintext
Callreveal() at the point of use and pass the result straight to whatever needs it.
Storing it in a field, logging it deliberately, or writing it into an output property defeats the
masking - the mask set covers the task log and captured output, not values you persist yourself.
toString() is always the mask, never the value, so a Secret is safe to include
in a log line, an exception message or a debugger view by accident.
- See Also:
-
Method Summary
-
Method Details
-
reveal
String reveal()The decrypted value, also registering it in this execution's mask set.Safe to call more than once; the value is decrypted once and the registration is idempotent.
- Returns:
- the plaintext, or
nullif the property is unset
-
toString
String toString()Always********- never the value.Overridden deliberately so that interpolating a
Secretinto a message cannot leak it. Usereveal()when you actually need the value.
-