public final class AssociatedData

Object
AssociatedData

The context an envelope is bound to, serialized to bytes exactly one way.

AES-GCM authenticates associated data without encrypting it, which is what lets an envelope refuse to open in the wrong place. Without a binding, an attacker who can write to the store can move a record: the ciphertext for account A, copied over account B’s entry, decrypts cleanly under the same data key and the application reads A’s secret as B’s. Every envelope this package writes therefore carries the application namespace, the vault, the record and the purpose in its associated data, and a decrypt that is handed a different four fails the tag.

Wire format

The serialization is fixed because two ports have to produce identical bytes or nothing interoperates. There is no map, no JSON and no separator character – a separator invites the ambiguity this exists to remove, where ("ab", "c") and ("a", "bc") serialize alike and the binding stops distinguishing them.

uint32  field count (always 4 in version 1)
repeat: uint32 byte length, then that many UTF-8 bytes

Fields, in order: application namespace, vault id, record id, purpose. A field the caller did not set is the empty string and still carries its length prefix. All integers are big-endian; the UTF-8 encoding is the one specified in this package rather than the platform’s.

Methods

`public static` `AssociatedData of(String application, String vault, String record)`	Binds to an application, a vault and a record.
`public static` `AssociatedData of(String application, String vault, String record, String purpose)`	The same with a purpose, which separates two envelopes that would otherwise share every field – the password wrap of a data key and its device wrap, for instance.
`public` `String getApplication()`	The application namespace this is bound to.
`public` `String getVault()`	The vault name this is bound to.
`public` `String getRecord()`	The record name this is bound to.
`public` `String getPurpose()`	The purpose this is bound to, or the empty string.
`public` `AssociatedData withPurpose(String newPurpose)`	A copy with a different purpose, so a caller can derive the several bindings one vault needs without repeating the first three fields.
`public` `AssociatedData withRecord(String newRecord)`	A copy bound to a different record.
`public byte[] serialize()`	The bytes fed to AES-GCM as associated data, in the format documented on this class.
`public` `String toString()`	A description safe to log: the field names are not secret, and none of them is the value an envelope protects.
`public boolean equals(Object other)`	Equality over the four fields, so a caller can assert a binding round-tripped.
`public int hashCode()`	Returns a hash code value for the object.

Inherited methods

From Object

getClass, notify, notifyAll, wait, wait, wait, clone

Method details

of

public static AssociatedData of(String application, String vault, String record)

Binds to an application, a vault and a record.

Parameters

application String: the application namespace, normally the package name
vault String: the vault name within the application
record String: the record, account or entry name

of

public static AssociatedData of(String application, String vault, String record, String purpose)

The same with a purpose, which separates two envelopes that would otherwise share every field – the password wrap of a data key and its device wrap, for instance.

getApplication

public String getApplication()

The application namespace this is bound to.

getVault

public String getVault()

The vault name this is bound to.

getRecord

public String getRecord()

The record name this is bound to.

getPurpose

public String getPurpose()

The purpose this is bound to, or the empty string.

withPurpose

public AssociatedData withPurpose(String newPurpose)

A copy with a different purpose, so a caller can derive the several bindings one vault needs without repeating the first three fields.

withRecord

public AssociatedData withRecord(String newRecord)

A copy bound to a different record.

serialize

public byte[] serialize()

The bytes fed to AES-GCM as associated data, in the format documented on this class.

toString

public String toString()

A description safe to log: the field names are not secret, and none of them is the value an envelope protects.

equals

public boolean equals(Object other)

Equality over the four fields, so a caller can assert a binding round-tripped.

hashCode

public int hashCode()

Returns a hash code value for the object. This method is supported for the benefit of hashtables such as those provided by java.util.Hashtable. The general contract of hashCode is: Whenever it is invoked on the same object more than once during an execution of a Java application, the hashCode method must consistently return the same integer, provided no information used in equals comparisons on the object is modified. This integer need not remain consistent from one execution of an application to another execution of the same application. If two objects are equal according to the equals(Object) method, then calling the hashCode method on each of the two objects must produce the same integer result. It is not required that if two objects are unequal according to the equals(java.lang.Object) method, then calling the hashCode method on each of the two objects must produce distinct integer results. However, the programmer should be aware that producing distinct integer results for unequal objects may improve the performance of hashtables. As much as is reasonably practical, the hashCode method defined by class Object does return distinct integers for distinct objects. (This is typically implemented by converting the internal address of the object into an integer, but this implementation technique is not required by the JavaTM programming language.)