Package org.cryptacular
Class CiphertextHeaderV2
java.lang.Object
org.cryptacular.CiphertextHeader
org.cryptacular.CiphertextHeaderV2
Cleartext header prepended to ciphertext providing data required for decryption.
Data format:
+---------+---------+---+----------+-------+------+ | Version | KeyName | 0 | NonceLen | Nonce | HMAC | +---------+---------+---+----------+-------+------+ | | +--- 4 ---+--- x ---+ 1 +--- 1 ----+-- y --+- 32 -+
Where fields are defined as follows:
- Version - Header version format as a negative number (4-byte integer). Current version is -2.
- KeyName - Symbolic key name encoded as UTF-8 bytes (variable length)
- 0 - Null byte signifying the end of the symbolic key name
- NonceLen - Nonce length in bytes (1-byte unsigned integer)
- Nonce - Nonce bytes (variable length)
- HMAC - HMAC-256 over preceding fields (32 bytes)
The last two fields 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.
- Author:
- Middleware Services
-
Field Summary
Fields inherited from class org.cryptacular.CiphertextHeader
keyName, length, MAX_KEYNAME_LEN, MAX_NONCE_LEN, nonce
-
Constructor Summary
ConstructorsConstructorDescriptionCiphertextHeaderV2
(byte[] nonce, String keyName) Creates a new instance with a nonce and named key. -
Method Summary
Modifier and TypeMethodDescriptionprotected int
static CiphertextHeaderV2
Creates a header from encrypted data containing a cleartext header prepended to the start.static CiphertextHeaderV2
decode
(InputStream input, Function<String, SecretKey> keyLookup) Creates a header from encrypted data containing a cleartext header prepended to the start.byte[]
encode()
Encodes the header into bytes.byte[]
Encodes the header into bytes.void
setKeyLookup
(Function<String, SecretKey> keyLookup) Sets the function to resolve keys fromCiphertextHeader.keyName
.Methods inherited from class org.cryptacular.CiphertextHeader
decode, decode, getKeyName, getLength, getNonce
-
Constructor Details
-
CiphertextHeaderV2
Creates a new instance with a nonce and named key.- Parameters:
nonce
- Nonce bytes.keyName
- Key name.
-
-
Method Details
-
setKeyLookup
Sets the function to resolve keys fromCiphertextHeader.keyName
.- Parameters:
keyLookup
- Key lookup function.
-
encode
public byte[] encode()Description copied from class:CiphertextHeader
Encodes the header into bytes.- Overrides:
encode
in classCiphertextHeader
- Returns:
- Byte representation of header.
-
encode
Encodes the header into bytes.- Parameters:
hmacKey
- Key used to generate header HMAC.- Returns:
- Byte representation of header.
-
computeLength
protected int computeLength()- Overrides:
computeLength
in classCiphertextHeader
- Returns:
- Length of this header encoded as bytes.
-
decode
public static CiphertextHeaderV2 decode(byte[] data, Function<String, SecretKey> keyLookup) throws EncodingExceptionCreates a header from encrypted data containing a cleartext header prepended to the start.- Parameters:
data
- Encrypted data with prepended header data.keyLookup
- Function used to look up the secret key from the symbolic key name in the header.- Returns:
- Decoded header.
- Throws:
EncodingException
- when ciphertext header cannot be decoded.
-
decode
public static CiphertextHeaderV2 decode(InputStream input, Function<String, SecretKey> keyLookup) throws EncodingException, StreamExceptionCreates 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.keyLookup
- Function used to look up the secret key from the symbolic key name in the header.- Returns:
- Decoded header.
- Throws:
EncodingException
- when ciphertext header cannot be decoded.StreamException
- on stream IO errors.
-