Merge "Unhide the enum/function for the password hashing algorithm scrypt" into pi-dev
am: 9ec7026e92

Change-Id: I0026b0ef43e9918811591f416a370dff84254df4
diff --git a/api/system-current.txt b/api/system-current.txt
index fa32383..d602b56 100644
--- a/api/system-current.txt
+++ b/api/system-current.txt
@@ -4349,11 +4349,14 @@
   }
 
   public final class KeyDerivationParams implements android.os.Parcelable {
+    method public static android.security.keystore.recovery.KeyDerivationParams createScryptParams(byte[], int);
     method public static android.security.keystore.recovery.KeyDerivationParams createSha256Params(byte[]);
     method public int describeContents();
     method public int getAlgorithm();
+    method public int getMemoryDifficulty();
     method public byte[] getSalt();
     method public void writeToParcel(android.os.Parcel, int);
+    field public static final int ALGORITHM_SCRYPT = 2; // 0x2
     field public static final int ALGORITHM_SHA256 = 1; // 0x1
     field public static final android.os.Parcelable.Creator<android.security.keystore.recovery.KeyDerivationParams> CREATOR;
   }
diff --git a/core/java/android/security/keystore/recovery/KeyDerivationParams.java b/core/java/android/security/keystore/recovery/KeyDerivationParams.java
index 428eaaa..8cb8e51 100644
--- a/core/java/android/security/keystore/recovery/KeyDerivationParams.java
+++ b/core/java/android/security/keystore/recovery/KeyDerivationParams.java
@@ -38,7 +38,7 @@
 public final class KeyDerivationParams implements Parcelable {
     private final int mAlgorithm;
     private final byte[] mSalt;
-    private final int mDifficulty;
+    private final int mMemoryDifficulty;
 
     /** @hide */
     @Retention(RetentionPolicy.SOURCE)
@@ -53,25 +53,32 @@
 
     /**
      * SCRYPT.
-     *
-     * @hide
      */
     public static final int ALGORITHM_SCRYPT = 2;
 
     /**
-     * Creates instance of the class to to derive key using salted SHA256 hash.
+     * Creates instance of the class to to derive keys using salted SHA256 hash.
+     *
+     * <p>The salted SHA256 hash is computed over the concatenation of four byte strings, salt_len +
+     * salt + key_material_len + key_material, where salt_len and key_material_len are one-byte, and
+     * denote the number of bytes for salt and key_material, respectively.
      */
     public static KeyDerivationParams createSha256Params(@NonNull byte[] salt) {
         return new KeyDerivationParams(ALGORITHM_SHA256, salt);
     }
 
     /**
-     * Creates instance of the class to to derive key using the password hashing algorithm SCRYPT.
+     * Creates instance of the class to to derive keys using the password hashing algorithm SCRYPT.
      *
-     * @hide
+     * <p>We expose only one tuning parameter of SCRYPT, which is the memory cost parameter (i.e. N
+     * in <a href="https://www.tarsnap.com/scrypt/scrypt.pdf">the SCRYPT paper</a>). Regular/default
+     * values are used for the other parameters, to keep the overall running time low. Specifically,
+     * the parallelization parameter p is 1, the block size parameter r is 8, and the hashing output
+     * length is 32-byte.
      */
-    public static KeyDerivationParams createScryptParams(@NonNull byte[] salt, int difficulty) {
-        return new KeyDerivationParams(ALGORITHM_SCRYPT, salt, difficulty);
+    public static KeyDerivationParams createScryptParams(
+            @NonNull byte[] salt, int memoryDifficulty) {
+        return new KeyDerivationParams(ALGORITHM_SCRYPT, salt, memoryDifficulty);
     }
 
     /**
@@ -79,17 +86,17 @@
      */
     // TODO: Make private once legacy API is removed
     public KeyDerivationParams(@KeyDerivationAlgorithm int algorithm, @NonNull byte[] salt) {
-        this(algorithm, salt, /*difficulty=*/ 0);
+        this(algorithm, salt, /*memoryDifficulty=*/ -1);
     }
 
     /**
      * @hide
      */
     KeyDerivationParams(@KeyDerivationAlgorithm int algorithm, @NonNull byte[] salt,
-            int difficulty) {
+            int memoryDifficulty) {
         mAlgorithm = algorithm;
         mSalt = Preconditions.checkNotNull(salt);
-        mDifficulty = difficulty;
+        mMemoryDifficulty = memoryDifficulty;
     }
 
     /**
@@ -107,12 +114,16 @@
     }
 
     /**
-     * Gets hashing difficulty.
+     * Gets the memory difficulty parameter for the hashing algorithm.
      *
-     * @hide
+     * <p>The effect of this parameter depends on the algorithm in use. For example, please see
+     * {@link #createScryptParams(byte[], int)} for choosing the parameter for SCRYPT.
+     *
+     * <p>If the specific algorithm does not support such a memory difficulty parameter, its value
+     * should be -1.
      */
-    public int getDifficulty() {
-        return mDifficulty;
+    public int getMemoryDifficulty() {
+        return mMemoryDifficulty;
     }
 
     public static final Parcelable.Creator<KeyDerivationParams> CREATOR =
@@ -130,7 +141,7 @@
     public void writeToParcel(Parcel out, int flags) {
         out.writeInt(mAlgorithm);
         out.writeByteArray(mSalt);
-        out.writeInt(mDifficulty);
+        out.writeInt(mMemoryDifficulty);
     }
 
     /**
@@ -139,7 +150,7 @@
     protected KeyDerivationParams(Parcel in) {
         mAlgorithm = in.readInt();
         mSalt = in.createByteArray();
-        mDifficulty = in.readInt();
+        mMemoryDifficulty = in.readInt();
     }
 
     @Override