Package 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 thePassphraseEncryptedOutputStream
when writing encrypted data, and that will be used by aPassphraseEncryptedInputStream
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 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.
-
-
-
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 benull
.passphrase
- The passphrase to use to generate the encryption key. If this isnull
, 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 anull
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 benull
or empty.passphrase
- The passphrase to use to generate the encryption key. If this isnull
, 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 anull
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, orfalse
if not.
-
toString
@NotNull public java.lang.String toString()
Retrieves a string representation of this passphrase-encrypted stream header.- Overrides:
toString
in classjava.lang.Object
- Returns:
- A string representation of this passphrase-encrypted stream header.
-
-