org.cryptacular

Class CiphertextHeader

java.lang.Object

org.cryptacular.CiphertextHeader

public class CiphertextHeader
extends java.lang.Object

Cleartext header prepended to ciphertext providing data required for decryption.

Data format:

     +-----+----------+-------+------------+---------+
     | Len | NonceLen | Nonce | KeyNameLen | KeyName |
     +-----+----------+-------+------------+---------+
 

Where fields are defined as follows:

• Len - Total header length in bytes (4-byte integer)
• NonceLen - Nonce length in bytes (4-byte integer)
• Nonce - Nonce bytes (variable length)
• KeyNameLen (OPTIONAL) - Key name length in bytes (4-byte integer)
• KeyName (OPTIONAL) - Key name encoded as bytes in platform-specific encoding (variable length)

The last two fields are optional and provide support for multiple keys at the encryption provider. A common case for multiple keys is key rotation; by tagging encrypted data with a key name, an old key may be retrieved by name to decrypt outstanding data which will be subsequently re-encrypted with a new key.

Field Summary

Fields

Modifier and Type	Field and Description
private java.lang.String	keyName Header key name field value.
private int	length Header length in bytes.
private byte[]	nonce Header nonce field value.

Constructor Summary

Constructors

Constructor and Description
CiphertextHeader(byte[] nonce) Creates a new instance with only a nonce.
CiphertextHeader(byte[] nonce, java.lang.String keyName) Creates a new instance with a nonce and named key.

Method Summary

Modifier and Type	Method and Description
static CiphertextHeader	decode(byte[] data) Creates a header from encrypted data containing a cleartext header prepended to the start.
static CiphertextHeader	decode(java.io.InputStream input) Creates a header from encrypted data containing a cleartext header prepended to the start.
byte[]	encode() Encodes the header into bytes.
java.lang.String	getKeyName() Gets the encryption key name stored in the header.
int	getLength() Gets the header length in bytes.
byte[]	getNonce() Gets the bytes of the nonce/IV.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

nonce

private final byte[] nonce

Header nonce field value.

keyName

private java.lang.String keyName

Header key name field value.

length

private int length

Header length in bytes.

Constructor Detail

CiphertextHeader

public CiphertextHeader(byte[] nonce)

Creates a new instance with only a nonce.

Parameters:

nonce - Nonce bytes.

CiphertextHeader

public CiphertextHeader(byte[] nonce,
                        java.lang.String keyName)

Creates a new instance with a nonce and named key.

Parameters:

nonce - Nonce bytes.

keyName - Key name.

Method Detail

getLength

public int getLength()

Gets the header length in bytes.

Returns:

Header length in bytes.

getNonce

public byte[] getNonce()

Gets the bytes of the nonce/IV.

Returns:

Nonce bytes.

getKeyName

public java.lang.String getKeyName()

Gets the encryption key name stored in the header.

Returns:

Encryption key name.

encode

public byte[] encode()

Encodes the header into bytes.

Returns:

Byte representation of header.

decode

public static CiphertextHeader decode(byte[] data)
                               throws EncodingException

Creates a header from encrypted data containing a cleartext header prepended to the start.

Parameters:

data - Encrypted data with prepended header data.

Returns:

Decoded header.

Throws:

EncodingException - when ciphertext header cannot be decoded.

decode

public static CiphertextHeader decode(java.io.InputStream input)
                               throws EncodingException,
                                      StreamException

Creates a header from encrypted data containing a cleartext header prepended to the start.

Parameters:

input - Input stream that is positioned at the start of ciphertext header data.

Returns:

Decoded header.

Throws:

EncodingException - when ciphertext header cannot be decoded.

StreamException - on stream IO errors.