Package com.unboundid.util

Class PassphraseEncryptedStreamHeader

java.lang.Object
com.unboundid.util.PassphraseEncryptedStreamHeader
All Implemented Interfaces:
Serializable
@NotMutable @ThreadSafety(level=MOSTLY_THREADSAFE) public final class PassphraseEncryptedStreamHeader extends Object implements Serializable
This class represents a data structure that will be used to hold information about the encryption performed by the PassphraseEncryptedOutputStream when writing encrypted data, and that will be used by a PassphraseEncryptedInputStream to obtain the settings needed to decrypt the encrypted data.

The data associated with this class is completely threadsafe. The methods used to interact with input and output streams are not threadsafe in that nothing else should be attempting to read from/write to the stream at the same time.
See Also:

  • Field Details

    • MAGIC_BYTES

      @NotNull public static final byte[] MAGIC_BYTES
      The "magic" value that will appear at the start of the header.

  • Method Details

    • writeTo

      public void writeTo(@NotNull OutputStream outputStream) throws IOException
      Writes an encoded representation of this passphrase-encrypted stream header to the provided output stream. The output stream will remain open after this method completes.
      Parameters:
      outputStream - The output stream to which the header will be written.
      Throws:
      IOException - If a problem is encountered while trying to write to the provided output stream.

    • readFrom

      @NotNull public static PassphraseEncryptedStreamHeader readFrom(@NotNull InputStream inputStream, @Nullable char[] passphrase) throws IOException, LDAPException, InvalidKeyException, GeneralSecurityException
      Reads a passphrase-encrypted stream header from the provided input stream. This method will not close the provided input stream, regardless of whether it returns successfully or throws an exception. If it returns successfully, then the position then the header bytes will have been consumed, so the next data to be read should be the data encrypted with these settings. If it throws an exception, then some unknown amount of data may have been read from the stream.
      Parameters:
      inputStream - The input stream from which to read the encoded passphrase-encrypted stream header. It must not be null.
      passphrase - The passphrase to use to generate the encryption key. If this is null, then the header will be read, but no attempt will be made to validate the MAC, and it will not be possible to use this header to actually perform encryption or decryption. Providing a null value is primarily useful if information in the header (especially the key identifier) is needed to determine what passphrase to use.
      Returns:
      The passphrase-encrypted stream header that was read from the provided input stream.
      Throws:
      IOException - If a problem is encountered while attempting to read data from the provided input stream.
      LDAPException - If a problem is encountered while attempting to decode the data that was read.
      InvalidKeyException - If the MAC contained in the header does not match the expected value.
      GeneralSecurityException - If a problem is encountered while trying to generate the MAC.

    • decode

      @NotNull public static PassphraseEncryptedStreamHeader decode(@NotNull byte[] encodedHeader, @Nullable char[] passphrase) throws LDAPException, InvalidKeyException, GeneralSecurityException
      Decodes the contents of the provided byte array as a passphrase-encrypted stream header. The provided array must contain only the header, with no additional data before or after.
      Parameters:
      encodedHeader - The bytes that comprise the header to decode. It must not be null or empty.
      passphrase - The passphrase to use to generate the encryption key. If this is null, then the header will be read, but no attempt will be made to validate the MAC, and it will not be possible to use this header to actually perform encryption or decryption. Providing a null value is primarily useful if information in the header (especially the key identifier) is needed to determine what passphrase to use.
      Returns:
      The passphrase-encrypted stream header that was decoded from the provided byte array.
      Throws:
      LDAPException - If a problem is encountered while trying to decode the data as a passphrase-encrypted stream header.
      InvalidKeyException - If the MAC contained in the header does not match the expected value.
      GeneralSecurityException - If a problem is encountered while trying to generate the MAC.

    • getKeyFactoryAlgorithm

      @NotNull public String getKeyFactoryAlgorithm()
      Retrieves the key factory algorithm used to generate the encryption key from the passphrase.
      Returns:
      The key factory algorithm used to generate the encryption key from the passphrase.

    • getKeyFactoryIterationCount

      public int getKeyFactoryIterationCount()
      Retrieves the iteration count used to generate the encryption key from the passphrase.
      Returns:
      The iteration count used to generate the encryption key from the passphrase.

    • getKeyFactorySalt

      @NotNull public byte[] getKeyFactorySalt()
      Retrieves the salt used to generate the encryption key from the passphrase.
      Returns:
      The salt used to generate the encryption key from the passphrase.

    • getKeyFactoryKeyLengthBits

      public int getKeyFactoryKeyLengthBits()
      Retrieves the length (in bits) of the encryption key generated from the passphrase.
      Returns:
      The length (in bits) of the encryption key generated from the passphrase.

    • getCipherTransformation

      @NotNull public String getCipherTransformation()
      Retrieves the cipher transformation used for the encryption.
      Returns:
      The cipher transformation used for the encryption.

    • getCipherInitializationVector

      @NotNull public byte[] getCipherInitializationVector()
      Retrieves the cipher initialization vector used for the encryption.
      Returns:
      The cipher initialization vector used for the encryption.

    • getKeyIdentifier

      @Nullable public String getKeyIdentifier()
      Retrieves the key identifier used to associate this passphrase-encrypted stream header with some other encryption settings object, if defined.
      Returns:
      The key identifier used to associate this passphrase-encrypted stream header with some other encryption settings object, or null if none was provided.

    • getMACAlgorithm

      @NotNull public String getMACAlgorithm()
      Retrieves the algorithm used to generate a MAC of the header content.
      Returns:
      The algorithm used to generate a MAC of the header content.

    • getEncodedHeader

      @NotNull public byte[] getEncodedHeader()
      Retrieves an encoded representation of this passphrase-encrypted stream header.
      Returns:
      An encoded representation of this passphrase-encrypted stream header.

    • isSecretKeyAvailable

      public boolean isSecretKeyAvailable()
      Indicates whether this passphrase-encrypted stream header includes a secret key. If this header was read or decoded with no passphrase provided, then it will not have a secret key, which means the MAC will not have been validated and it cannot be used to encrypt or decrypt data.
      Returns:
      true if this passphrase-encrypted stream header includes a secret key and can be used to encrypt or decrypt data, or false if not.

    • toString

      @NotNull public String toString()
      Retrieves a string representation of this passphrase-encrypted stream header.
      Overrides:
      toString in class Object
      Returns:
      A string representation of this passphrase-encrypted stream header.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this passphrase-encrypted stream header to the provided buffer.
      Parameters:
      buffer - The buffer to which the information should be appended.