Update Javadocs to reflect meaning of digest and padding NONE.

This also adds information about what digests and paddings may need to
be specified for keys used in TLS/SSL for client or server
authentication.

Bug: 21777596
Change-Id: Icd495458c38c4f912b21a64ca7aab2c88d76461c

5 files changed, 42 insertions, 38 deletions

diff --git a/keystore/java/android/security/keystore/AndroidKeyStoreKeyPairGeneratorSpi.java b/keystore/java/android/security/keystore/AndroidKeyStoreKeyPairGeneratorSpi.java
index 35af34f..c8ecbcd 100644
--- a/keystore/java/android/security/keystore/AndroidKeyStoreKeyPairGeneratorSpi.java
+++ b/keystore/java/android/security/keystore/AndroidKeyStoreKeyPairGeneratorSpi.java
@@ -215,14 +215,8 @@ public abstract class AndroidKeyStoreKeyPairGeneratorSpi extends KeyPairGenerato
                                     legacySpec.getKeystoreAlias(),
                                     KeyProperties.PURPOSE_SIGN
                                     | KeyProperties.PURPOSE_VERIFY);
-                            specBuilder.setDigests(
-                                    KeyProperties.DIGEST_NONE,
-                                    KeyProperties.DIGEST_MD5,
-                                    KeyProperties.DIGEST_SHA1,
-                                    KeyProperties.DIGEST_SHA224,
-                                    KeyProperties.DIGEST_SHA256,
-                                    KeyProperties.DIGEST_SHA384,
-                                    KeyProperties.DIGEST_SHA512);
+                            // Authorized to be used with any digest (including no digest).
+                            specBuilder.setDigests(KeyProperties.DIGEST_NONE);
                             break;
                         case KeymasterDefs.KM_ALGORITHM_RSA:
                             specBuilder = new KeyGenParameterSpec.Builder(
@@ -231,19 +225,13 @@ public abstract class AndroidKeyStoreKeyPairGeneratorSpi extends KeyPairGenerato
                                     | KeyProperties.PURPOSE_DECRYPT
                                     | KeyProperties.PURPOSE_SIGN
                                     | KeyProperties.PURPOSE_VERIFY);
-                            specBuilder.setDigests(
-                                    KeyProperties.DIGEST_NONE,
-                                    KeyProperties.DIGEST_MD5,
-                                    KeyProperties.DIGEST_SHA1,
-                                    KeyProperties.DIGEST_SHA224,
-                                    KeyProperties.DIGEST_SHA256,
-                                    KeyProperties.DIGEST_SHA384,
-                                    KeyProperties.DIGEST_SHA512);
+                            // Authorized to be used with any digest (including no digest).
+                            specBuilder.setDigests(KeyProperties.DIGEST_NONE);
                             specBuilder.setSignaturePaddings(
                                     KeyProperties.SIGNATURE_PADDING_RSA_PKCS1);
+                            // Authorized to be used with any padding (including no padding).
                             specBuilder.setEncryptionPaddings(
-                                    KeyProperties.ENCRYPTION_PADDING_NONE,
-                                    KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1);
+                                    KeyProperties.ENCRYPTION_PADDING_NONE);
                             // Disable randomized encryption requirement to support encryption
                             // padding NONE above.
                             specBuilder.setRandomizedEncryptionRequired(false);
diff --git a/keystore/java/android/security/keystore/AndroidKeyStoreSpi.java b/keystore/java/android/security/keystore/AndroidKeyStoreSpi.java
index 831a106..3bd9d1d 100644
--- a/keystore/java/android/security/keystore/AndroidKeyStoreSpi.java
+++ b/keystore/java/android/security/keystore/AndroidKeyStoreSpi.java
@@ -247,14 +247,8 @@ public class AndroidKeyStoreSpi extends KeyStoreSpi {
             specBuilder =
                     new KeyProtection.Builder(
                             KeyProperties.PURPOSE_SIGN | KeyProperties.PURPOSE_VERIFY);
-            specBuilder.setDigests(
-                    KeyProperties.DIGEST_NONE,
-                    KeyProperties.DIGEST_MD5,
-                    KeyProperties.DIGEST_SHA1,
-                    KeyProperties.DIGEST_SHA224,
-                    KeyProperties.DIGEST_SHA256,
-                    KeyProperties.DIGEST_SHA384,
-                    KeyProperties.DIGEST_SHA512);
+            // Authorized to be used with any digest (including no digest).
+            specBuilder.setDigests(KeyProperties.DIGEST_NONE);
         } else if (KeyProperties.KEY_ALGORITHM_RSA.equalsIgnoreCase(keyAlgorithm)) {
             specBuilder =
                     new KeyProtection.Builder(
@@ -262,19 +256,13 @@ public class AndroidKeyStoreSpi extends KeyStoreSpi {
                             | KeyProperties.PURPOSE_DECRYPT
                             | KeyProperties.PURPOSE_SIGN
                             | KeyProperties.PURPOSE_VERIFY);
-            specBuilder.setDigests(
-                    KeyProperties.DIGEST_NONE,
-                    KeyProperties.DIGEST_MD5,
-                    KeyProperties.DIGEST_SHA1,
-                    KeyProperties.DIGEST_SHA224,
-                    KeyProperties.DIGEST_SHA256,
-                    KeyProperties.DIGEST_SHA384,
-                    KeyProperties.DIGEST_SHA512);
+            // Authorized to be used with any digest (including no digest).
+            specBuilder.setDigests(KeyProperties.DIGEST_NONE);
             specBuilder.setSignaturePaddings(
                     KeyProperties.SIGNATURE_PADDING_RSA_PKCS1);
+            // Authorized to be used with any padding (including no padding).
             specBuilder.setEncryptionPaddings(
-                    KeyProperties.ENCRYPTION_PADDING_NONE,
-                    KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1);
+                    KeyProperties.ENCRYPTION_PADDING_NONE);
             // Disable randomized encryption requirement to support encryption padding NONE
             // above.
             specBuilder.setRandomizedEncryptionRequired(false);
diff --git a/keystore/java/android/security/keystore/KeyGenParameterSpec.java b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
index 68c9c79..47aab74 100644
--- a/keystore/java/android/security/keystore/KeyGenParameterSpec.java
+++ b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
@@ -611,9 +611,14 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
          *
          * <p>This must be specified for keys which are used for signing/verification. For HMAC
          * keys, the set of digests defaults to the digest associated with the key algorithm (e.g.,
-         * {@code SHA-256} for key algorithm {@code HmacSHA256}
+         * {@code SHA-256} for key algorithm {@code HmacSHA256}).
          *
-         * @see KeyProperties.Digest
+         * <p>For private keys used for TLS/SSL client or server authentication it is usually
+         * necessary to authorize the use of no digest ({@link KeyProperties#DIGEST_NONE}). This is
+         * because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use
+         * a private key to sign it.
+         *
+         * <p>See {@link KeyProperties}.{@code DIGEST} constants.
          */
         @NonNull
         public Builder setDigests(@KeyProperties.DigestEnum String... digests) {
@@ -629,6 +634,12 @@ public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
          *
          * <p>This must be specified for keys which are used for encryption/decryption.
          *
+         * <p>For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it
+         * is usually necessary to authorize the use of no/any padding
+         * ({@link KeyProperties#ENCRYPTION_PADDING_NONE}). This is because RSA decryption is
+         * required by some cipher suites, and some stacks request decryption using no padding
+         * whereas others request PKCS#1 padding.
+         *
          * <p>See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
          */
         @NonNull
diff --git a/keystore/java/android/security/keystore/KeyProperties.java b/keystore/java/android/security/keystore/KeyProperties.java
index 5af4181..403e814 100644
--- a/keystore/java/android/security/keystore/KeyProperties.java
+++ b/keystore/java/android/security/keystore/KeyProperties.java
@@ -368,6 +368,9 @@ public abstract class KeyProperties {
 
     /**
      * No encryption padding.
+     *
+     * <p><b>NOTE</b>: If a key is authorized to be used with no padding, then it can be used with
+     * any padding scheme.
      */
     public static final String ENCRYPTION_PADDING_NONE = "NoPadding";
 
@@ -514,6 +517,9 @@ public abstract class KeyProperties {
 
     /**
      * No digest: sign/authenticate the raw message.
+     *
+     * <p><b>NOTE</b>: If a key is authorized to be used with no digest, then it can be used with
+     * any digest.
      */
     public static final String DIGEST_NONE = "NONE";
 
diff --git a/keystore/java/android/security/keystore/KeyProtection.java b/keystore/java/android/security/keystore/KeyProtection.java
index 48c0ed0..432fc12 100644
--- a/keystore/java/android/security/keystore/KeyProtection.java
+++ b/keystore/java/android/security/keystore/KeyProtection.java
@@ -374,6 +374,12 @@ public final class KeyProtection implements ProtectionParameter {
          *
          * <p>This must be specified for keys which are used for encryption/decryption.
          *
+         * <p>For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it
+         * is usually necessary to authorize the use of no/any padding
+         * ({@link KeyProperties#ENCRYPTION_PADDING_NONE}). This is because RSA decryption is
+         * required by some cipher suites, and some stacks request decryption using no padding
+         * whereas others request PKCS#1 padding.
+         *
          * <p>See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
          */
         @NonNull
@@ -408,6 +414,11 @@ public final class KeyProtection implements ProtectionParameter {
          * {@link Key#getAlgorithm()}. For asymmetric signing keys the set of digest algorithms
          * must be specified.
          *
+         * <p>For private keys used for TLS/SSL client or server authentication it is usually
+         * necessary to authorize the use of no digest ({@link KeyProperties#DIGEST_NONE}). This is
+         * because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use
+         * a private key to sign it.
+         *
          * <p>See {@link KeyProperties}.{@code DIGEST} constants.
          */
         @NonNull