Interface Secret


public interface Secret
A password-typed property value, kept encrypted until you ask for it.

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

Call reveal() 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

    Modifier and Type
    Method
    Description
    The decrypted value, also registering it in this execution's mask set.
    Always ******** - never the value.
  • 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 null if the property is unset
    • toString

      String toString()
      Always ******** - never the value.

      Overridden deliberately so that interpolating a Secret into a message cannot leak it. Use reveal() when you actually need the value.

      Overrides:
      toString in class Object