AO Security Changelog

1. Defensive copies of byte[] returned by HashedKey and HashedPassword.
2. Implemented meaningful hashCode() methods on UnprotectedKey and UnprotectedPassword.

1. HashedKey.Algorithm.validateHash-function.sql
2. HashedPassword.Algorithm.validate-function.sql

Created a new pair of classes Password and UnprotectedPassword that should be used to encapsulate plaintext passwords instead of using char[] or String. Instances are Destroyable.

All uses are aggressively destroyed, thus requiring the caller to actively clone when the password is still required. Thus, programmer errors should be in the direction of safety: no action means password is destroyed.

Deprecated the String-based representations of passwords, in favor of the aggressively destroyed Password.

Created a new pair of classes Key and UnprotectedKey that should be used to encapsulate keys instead of working directly with byte[]. Instances are Destroyable.

All uses are aggressively destroyed, thus requiring the caller to actively clone when the key is still required. Thus, programmer errors should be in the direction of safety: no action means key is destroyed.

Deprecated the byte[]-based representations of keys, in favor of the aggressively destroyed Key.

generateKey(…) now returns UnprotectedKey instead of byte[], which is a breaking change. This is major version increment.

1. BEGIN;
   
   ALTER TYPE "com.aoindustries.security"."HashedKey"       RENAME TO "<HashedKey>";
   ALTER TYPE "com.aoindustries.security"."HashedPassword"  RENAME TO "<HashedPassword>";
   ALTER TYPE "com.aoindustries.security"."Identifier"      RENAME TO "<Identifier>";
   
   COMMENT ON TYPE "com.aoindustries.security"."<HashedKey>" IS
   'Row definition for "com.aoindustries.security"."HashedKey"';
   COMMENT ON TYPE "com.aoindustries.security"."<HashedPassword>" IS
   'Row definition for "com.aoindustries.security"."HashedPassword"';
   COMMENT ON TYPE "com.aoindustries.security"."<Identifier>" IS
   'Row definition for "com.aoindustries.security"."Identifier"';
   
   CREATE DOMAIN "com.aoindustries.security"."HashedKey" AS "com.aoindustries.security"."<HashedKey>" CHECK (
     VALUE IS NOT DISTINCT FROM NULL
     OR "com.aoindustries.security"."HashedKey.validate"(VALUE) IS NULL
   );
   CREATE DOMAIN "com.aoindustries.security"."HashedPassword" AS "com.aoindustries.security"."<HashedPassword>" CHECK (
     VALUE IS NOT DISTINCT FROM NULL
     OR "com.aoindustries.security"."HashedPassword.validate"(VALUE) IS NULL
   );
   CREATE DOMAIN "com.aoindustries.security"."Identifier" AS "com.aoindustries.security"."<Identifier>" CHECK (
     VALUE IS NOT DISTINCT FROM NULL
     OR "com.aoindustries.security"."Identifier.validate"(VALUE) IS NULL
   );
   
   COMMENT ON DOMAIN "com.aoindustries.security"."HashedKey" IS
   'Matches class com.aoindustries.security.HashedKey';
   COMMENT ON DOMAIN "com.aoindustries.security"."HashedPassword" IS
   'Matches class com.aoindustries.security.HashedPassword';
   COMMENT ON DOMAIN "com.aoindustries.security"."Identifier" IS
   'Matches class com.aoindustries.security.Identifier';
   
   COMMIT;

2. Recreate all functions, for "PARALLEL SAFE" and type changes.
3. Update your column types
4. Drop the unnecessary column check constraints

Reverted back to generating keys with as many bits as their corresponding hash function (with the exception of SHA-1). Keys themselves are subject to the birthday paradox and should thus be as long as the hash.

We have set SHA-1 to a key of 128 bits, however, which is roughly double its currently estimated collision resistance of 65 bits. But, SHA-1 is deprecated, so this shouldn't matter.

With this change, we have restored the recommended algorithm to the previous SHA-256 so that URL parameter and cookie value lengths will not change. We believe SHA-512 would be overkill, especially considering it is a hash of an equally-sized random key.

1. New constant NO_KEY that must be used when there is no key.
2. Now supports multiple algorithms, with the recommended algorithm being "SHA-512". Previously, all keys were "SHA-256".

3. For the SHA-* algorithms (with the exception of SHA-1 explained below), the key length now defaults to half that of the hash length. This is selected so the likelihood to guess the original key is equal to the hash's expected collision resistance.

   NIST 800-107: 4.1 Hash Function Properties:

   The expected collision-resistance strength of a hash function is half the length of the hash value produced by that hash function.

   SHA-256 still allows a 256-bit key for compatibility, but new keys will be generated with 128 bits. However, given that the default algorithm has also been changed to "SHA-512", expect the same default key length (URL parameter and cookie value lengths will not change).

   For SHA-1, which is deprecated and should not be used anyway, we have further reduced the key size to 64 bits (instead of the 80 bits it would be if assumed half the hash size). This is because SHA-1 is now considered to have at best 65-bits of collision resistance. If using SHA-1 (which you shouldn't) its key size is correspondingly limited to 64 bits. See:

   • Why it’s harder to forge a SHA-1 certificate than it is to find a SHA-1 collision
   • Attacks on Hash Functions and Applications - PhD Thesis Marc Stevens - Attacks on Hash Functions and Applications.pdf
4. Length-constant time equality checks
5. compareTo(HashedKey) now orders unsigned

6. toString() and a new valueOf(String) now represent the hashed key in an unambiguous string format. "*" represents "No key".

   This may be used to insert the password into a database, and it is compatible with AutoObjectFactory. However, a PostgreSQL composite type is provided in the alternate "sql" classifier. This type is more compact and enforces much more integrity than just stuffing the value in as a string.

7. Is now Serializable.
8. New main method that can be used to generate a key and hash pair. Includes a -b option for benchmark mode, which runs all algorithms and gives timings.

1. New constant NO_PASSWORD that must be used when there is no password.
2. Now supports multiple algorithms, with the recommended algorithm being "PBKDF2WithHmacSHA512".
3. Per-algorithm recommended iterations, with values increased significantly higher than the previously recommended 1000. Recommended values are selected to complete the hashing in around 100 ms on commodity PC hardware from around the year 2012.
4. New method isRehashRecommended() that provides a hint when the password should be rehashed during login.

5. toString() and a new valueOf(String) now represent the hashed password in an unambiguous string format. "*" represents "No key".

   This may be used to insert the password into a database, and it is compatible with AutoObjectFactory. However, a PostgreSQL composite type is provided in the alternate "sql" classifier. This type is more compact and enforces much more integrity than just stuffing the value in as a string.

6. Is now Serializable.
7. New main method that can be used to hash passwords. Includes a -b option for benchmark mode, which runs all algorithms, gives timings, and will recommend increasing recommendedIterations when a hash is performed in under 100 ms.
8. Unit tests will now issue a warning to suggest increasing default iterations when an algorithm completes in under 100 ms.
9. Convenience constructors that perform all the steps of generating salt and hash.