Class AssociatedData

java.lang.Object
com.codename1.security.vault.AssociatedData
public final class AssociatedData extends Object

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.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    equals(Object other)
    Equality over the four fields, so a caller can assert a binding round-tripped.
    String
    getApplication()
    The application namespace this is bound to.
    String
    getPurpose()
    The purpose this is bound to, or the empty string.
    String
    getRecord()
    The record name this is bound to.
    String
    getVault()
    The vault name this is bound to.
    int
    hashCode()
    Returns a hash code value for the object.
    static AssociatedData
    of(String application, String vault, String record)
    Binds to an application, a vault and a record.
    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.
    byte[]
    serialize()
    The bytes fed to AES-GCM as associated data, in the format documented on this class.
    String
    toString()
    A description safe to log: the field names are not secret, and none of them is the value an envelope protects.
    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.
    AssociatedData
    withRecord(String newRecord)
    A copy bound to a different record.

    Methods inherited from class Object

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

  • Method Details

    • of

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

      Binds to an application, a vault and a record.

      Parameters

      • application: the application namespace, normally the package name

      • vault: the vault name within the application

      • record: 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.
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object other)
      Equality over the four fields, so a caller can assert a binding round-tripped.
      Overrides:
      equals in class Object

    • hashCode

      public int hashCode()
      Description copied from class: Object
      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.)
      Overrides:
      hashCode in class Object