com.unboundid.util

Class PassphraseEncryptedStreamHeader

java.lang.Object

com.unboundid.util.PassphraseEncryptedStreamHeader

All Implemented Interfaces:

java.io.Serializable

@NotMutable
 @ThreadSafety(level=MOSTLY_THREADSAFE)
public final class PassphraseEncryptedStreamHeader
extends java.lang.Object
implements java.io.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:

Serialized Form

Field Summary

Fields

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

Method Summary

Modifier and Type	Method and 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

@NotNull
public static final byte[] MAGIC_BYTES

The "magic" value that will appear at the start of the header.

Method Detail

writeTo

public void writeTo(@NotNull
                    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

@NotNull
public static PassphraseEncryptedStreamHeader readFrom(@NotNull
                                                                java.io.InputStream inputStream,
                                                                @Nullable
                                                                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

@NotNull
public static PassphraseEncryptedStreamHeader decode(@NotNull
                                                              byte[] encodedHeader,
                                                              @Nullable
                                                              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

@NotNull
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

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

@NotNull
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

@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 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(@NotNull
                     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.