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