Class SecretBytes

  • All Implemented Interfaces:
    Serializable

    public class SecretBytes
    extends Object
    implements Serializable
    An analogue of Secret to be used for efficient storage of byte[]. The serialized form will embed the salt and padding so no two invocations of getEncryptedData() will return the same result, but all will decrypt to the same getPlainData(). XStream serialization and Stapler form-binding will assume that the toString() representation is used (i.e. the Base64 encoded secret bytes wrapped with { and }. If the string representation fails to decrypt (and is not wrapped
    Since:
    2.1.5
    See Also:
    Serialized Form
    • Field Detail

      • ENCRYPTED_VALUE_PATTERN

        @Restricted(org.kohsuke.accmod.restrictions.NoExternalUse.class)
        public static final Pattern ENCRYPTED_VALUE_PATTERN
        Pattern matching a possible output of toString(). Basically, any Base64-encoded value. You must then call decrypt(byte[]) to eliminate false positives.
    • Method Detail

      • getPlainData

        @NonNull
        public byte[] getPlainData()
        Returns the raw unencrypted data. The caller is responsible for zeroing out the returned byte[] after use.
        Returns:
        the raw unencrypted data.
      • hashCode

        public int hashCode()
        Overrides:
        hashCode in class Object
      • getEncryptedData

        @NonNull
        public byte[] getEncryptedData()
        Returns the encrypted data.
        Returns:
        the encrypted data.
      • decrypt

        @CheckForNull
        public static SecretBytes decrypt​(byte[] data)
        Reverse operation of getEncryptedData(). Returns null if the given cipher text was invalid.
        Parameters:
        data - the bytes to decrypt.
        Returns:
        the secret bytes or null if the data was not originally encrypted.
      • getPlainData

        @NonNull
        public static byte[] getPlainData​(@CheckForNull
                                          SecretBytes s)
        Works just like getPlainData() but avoids NPE when the secret is null. To be consistent with fromBytes(byte[]), this method doesn't distinguish empty password and null password.
        Parameters:
        s - the secret bytes.
        Returns:
        the decrypted bytes.
      • fromBytes

        public static SecretBytes fromBytes​(byte[] data)
        Attempts to treat the given bytes first as a cipher encrypted bytes, and if it doesn't work, treat the given bytes as the unencrypted secret value.

        Useful for recovering a value from a form field. If the supplied bytes are known to be unencrypted then the caller is responsible for zeroing out the supplied byte[] afterwards.

        Parameters:
        data - the data to wrap or decrypt.
        Returns:
        never null
      • fromString

        @NonNull
        public static SecretBytes fromString​(String data)
        Attempts to treat the given bytes first as a cipher text, and if it doesn't work, treat the given string as the unencrypted BASE-64 encoded byte array.

        Useful for recovering a value from a form field. Note: the caller is responsible for evicting the data from memory in the event that the data is the unencrypted BASE-64 encoded plain data.

        Parameters:
        data - the string representation to decrypt.
        Returns:
        never null
      • isSecretBytes

        public static boolean isSecretBytes​(String data)
        check if the given String is a SecretBytes text by attempting to decrypt it
        Parameters:
        data - the string to check
        Returns:
        true if the decryption was successful, false otherwise
      • toString

        public static String toString​(SecretBytes s)
        Works just like toString() but avoids NPE when the secret is null. To be consistent with fromString(String), this method doesn't distinguish empty password and null password.
        Parameters:
        s - the secret bytes.
        Returns:
        the string representation.