Class KdfProfile

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

The portable password key derivation this package uses, as a versioned profile rather than a set of numbers each caller picks.

Why PBKDF2 and not something better

Argon2id and scrypt are better password KDFs, and neither exists in a browser. Web Crypto implements exactly one -- PBKDF2 -- and a password vault whose whole point is that Android, iOS and the browser derive the same key from the same password cannot use a KDF that one of the three has to emulate in application code. A JavaScript Argon2 would be orders of magnitude slower than the native one the phone uses, which in practice means the parameters get lowered until the browser is usable and every platform is then weaker than PBKDF2 would have been.

So: PBKDF2-HMAC-SHA256, with the iteration count carried in the envelope so it can be raised without breaking anything already written. current() is what new material is derived with; needsUpgrade() tells a caller that an envelope it just opened was written under a weaker profile and should be rewrapped.

Bounds

The iteration count is clamped into MIN_ITERATIONS to MAX_ITERATIONS on the way in and rejected rather than clamped on the way out of a parsed envelope. The asymmetry is the point: an attacker who can edit stored bytes would otherwise set the count to 1 and turn a password check into a guessable one, or set it to two billion and make the application hang on open. A count outside the range in a stored envelope is VaultError.UNSUPPORTED_FORMAT.

Where the work happens

The derivation is one native call on every port that has one (Util.pbkdf2(String, byte[], byte[], int, int)), and a pure Java loop over Hmac where there is none. The pure Java path produces identical bytes -- it is RFC 8018 with no latitude in it -- but 600000 iterations of software HMAC is slow enough to be a problem, so a port without the hook should add one rather than rely on it.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final int
    DEFAULT_ITERATIONS
    What new material is derived with today.
    static final int
    DIRECT
    No derivation: the envelope is sealed directly under a key the caller already has.
    static final int
    MAX_ITERATIONS
    Above this the derivation is a denial of service against the user's own device.
    static final int
    MIN_ITERATIONS
    Below this an iteration count is not a password KDF, it is a formality.
    static final int
    PBKDF2_HMAC_SHA256
    PBKDF2 with HMAC-SHA-256, the only KDF identifier version 1 of the envelope defines.
    static final int
    SALT_LENGTH
    The salt length this package generates.

  • Method Summary

    Modifier and Type
    Method
    Description
    static KdfProfile
    current()
    The profile new material should be derived with.
    byte[]
    derive(char[] password, byte[] salt, int length)
    Derives length bytes from a password and salt.
    boolean
    equals(Object other)
    Indicates whether some other object is "equal to" this one.
    int
    getIterations()
    The iteration count, or zero for DIRECT.
    int
    getKdfId()
    The envelope's KDF identifier: PBKDF2_HMAC_SHA256 or DIRECT.
    int
    hashCode()
    Returns a hash code value for the object.
    boolean
    needsUpgrade()
    Whether material written under this profile should be rewrapped under current().
    static KdfProfile
    pbkdf2(int iterations)
    A profile with an explicit iteration count, clamped into the supported range.
    String
    toString()
    Returns a string representation of the object.

    Methods inherited from class Object

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

  • Field Details

    • PBKDF2_HMAC_SHA256

      public static final int PBKDF2_HMAC_SHA256
      PBKDF2 with HMAC-SHA-256, the only KDF identifier version 1 of the envelope defines.
      See Also:

    • DIRECT

      public static final int DIRECT
      No derivation: the envelope is sealed directly under a key the caller already has.
      See Also:

    • MIN_ITERATIONS

      public static final int MIN_ITERATIONS
      Below this an iteration count is not a password KDF, it is a formality. OWASP's 2023 floor for PBKDF2-HMAC-SHA256 is 600000; 100000 is the oldest count this will still open material written under, and needsUpgrade() reports it.
      See Also:

    • MAX_ITERATIONS

      public static final int MAX_ITERATIONS
      Above this the derivation is a denial of service against the user's own device. Ten million iterations is roughly a minute of a phone's time.
      See Also:

    • DEFAULT_ITERATIONS

      public static final int DEFAULT_ITERATIONS
      What new material is derived with today. Raising this is a compatible change: existing envelopes carry their own count and keep opening.
      See Also:

    • SALT_LENGTH

      public static final int SALT_LENGTH
      The salt length this package generates. Sixteen bytes of fresh randomness per envelope, which is what stops one precomputation covering two users.
      See Also:

  • Method Details

    • current

      public static KdfProfile current()
      The profile new material should be derived with.

    • pbkdf2

      public static KdfProfile pbkdf2(int iterations)

      A profile with an explicit iteration count, clamped into the supported range.

      Clamping rather than throwing because this is the caller-facing constructor and a caller asking for 1000 iterations has made a mistake worth correcting silently upward. The parsing path does not clamp -- see forStored(int, int).

      Parameters
      • iterations: the requested count

    • getKdfId

      public int getKdfId()
      The envelope's KDF identifier: PBKDF2_HMAC_SHA256 or DIRECT.

    • getIterations

      public int getIterations()
      The iteration count, or zero for DIRECT.

    • needsUpgrade

      public boolean needsUpgrade()

      Whether material written under this profile should be rewrapped under current().

      True for anything weaker than today's default. An application that opens a vault, sees this, and has the password in hand should re-derive and rewrite; one that does not can carry on, because the envelope still opens.

    • derive

      public byte[] derive(char[] password, byte[] salt, int length)

      Derives length bytes from a password and salt.

      Parameters

      • password: the password, as characters so the caller can clear them. Encoded with this package's UTF-8 and not normalized -- see [Bytes#utf8(char[])].

      • salt: fresh per envelope, at least SALT_LENGTH bytes for new material

      • length: how many bytes to produce, normally 32 for an AES-256 key

      Returns

      the derived bytes, which the caller owns and should clear

    • toString

      public String toString()
      Description copied from class: Object
      Returns a string representation of the object. In general, the toString method returns a string that "textually represents" this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@', and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + '@' + Integer.toHexString(hashCode())
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object other)
      Description copied from class: Object
      Indicates whether some other object is "equal to" this one. The equals method implements an equivalence relation: It is reflexive: for any reference value x, x.equals(x) should return true. It is symmetric: for any reference values x and y, x.equals(y) should return true if and only if y.equals(x) returns true. It is transitive: for any reference values x, y, and z, if x.equals(y) returns true and y.equals(z) returns true, then x.equals(z) should return true. It is consistent: for any reference values x and y, multiple invocations of x.equals(y) consistently return true or consistently return false, provided no information used in equals comparisons on the object is modified. For any non-null reference value x, x.equals(null) should return false. The equals method for class Object implements the most discriminating possible equivalence relation on objects; that is, for any reference values x and y, this method returns true if and only if x and y refer to the same object (x==y has the value true).
      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