Class PassphraseEncryptedStreamHeader

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static byte[] MAGIC_BYTES
      The "magic" value that will appear at the start of the header.
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      static PassphraseEncryptedStreamHeader decode​(byte[] encodedHeader, char[] passphrase)
      Decodes the contents of the provided byte array as a passphrase-encrypted stream header.
      byte[] getCipherInitializationVector()
      Retrieves the cipher initialization vector used for the encryption.
      java.lang.String getCipherTransformation()
      Retrieves the cipher transformation used for the encryption.
      byte[] getEncodedHeader()
      Retrieves an encoded representation of this passphrase-encrypted stream header.
      java.lang.String getKeyFactoryAlgorithm()
      Retrieves the key factory algorithm used to generate the encryption key from the passphrase.
      int getKeyFactoryIterationCount()
      Retrieves the iteration count used to generate the encryption key from the passphrase.
      int getKeyFactoryKeyLengthBits()
      Retrieves the length (in bits) of the encryption key generated from the passphrase.
      byte[] getKeyFactorySalt()
      Retrieves the salt used to generate the encryption key from the passphrase.
      java.lang.String getKeyIdentifier()
      Retrieves the key identifier used to associate this passphrase-encrypted stream header with some other encryption settings object, if defined.
      java.lang.String getMACAlgorithm()
      Retrieves the algorithm used to generate a MAC of the header content.
      boolean isSecretKeyAvailable()
      Indicates whether this passphrase-encrypted stream header includes a secret key.
      static PassphraseEncryptedStreamHeader readFrom​(java.io.InputStream inputStream, char[] passphrase)
      Reads a passphrase-encrypted stream header from the provided input stream.
      java.lang.String toString()
      Retrieves a string representation of this passphrase-encrypted stream header.
      void toString​(java.lang.StringBuilder buffer)
      Appends a string representation of this passphrase-encrypted stream header to the provided buffer.
      void writeTo​(java.io.OutputStream outputStream)
      Writes an encoded representation of this passphrase-encrypted stream header to the provided output stream.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • MAGIC_BYTES

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

      • writeTo

        public void writeTo​(java.io.OutputStream outputStream)
                     throws java.io.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:
        java.io.IOException - If a problem is encountered while trying to write to the provided output stream.
      • readFrom

        public static PassphraseEncryptedStreamHeader readFrom​(java.io.InputStream inputStream,
                                                               char[] passphrase)
                                                        throws java.io.IOException,
                                                               LDAPException,
                                                               java.security.InvalidKeyException,
                                                               java.security.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:
        java.io.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.
        java.security.InvalidKeyException - If the MAC contained in the header does not match the expected value.
        java.security.GeneralSecurityException - If a problem is encountered while trying to generate the MAC.
      • decode

        public static PassphraseEncryptedStreamHeader decode​(byte[] encodedHeader,
                                                             char[] passphrase)
                                                      throws LDAPException,
                                                             java.security.InvalidKeyException,
                                                             java.security.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.
        java.security.InvalidKeyException - If the MAC contained in the header does not match the expected value.
        java.security.GeneralSecurityException - If a problem is encountered while trying to generate the MAC.
      • getKeyFactoryAlgorithm

        public java.lang.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

        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

        public java.lang.String getCipherTransformation()
        Retrieves the cipher transformation used for the encryption.
        Returns:
        The cipher transformation used for the encryption.
      • getCipherInitializationVector

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

        public java.lang.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

        public java.lang.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

        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

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

        public void toString​(java.lang.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.