Document when self-signed certs have invalid signature.

This updates the Javadocs of Android Keystore to explain what key
authorizations are needed for the self-signed cert create at key
generation time to have a valid signature.

Bug: 18088752
Bug: 21777596
Change-Id: Id02425133f094a0c5a02e96f4c63aab7175cba5b

2 files changed, 9 insertions, 1 deletions

diff --git a/keystore/java/android/security/keystore/KeyGenParameterSpec.java b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
index 47aab74..4c0631f 100644
--- a/keystore/java/android/security/keystore/KeyGenParameterSpec.java
+++ b/keystore/java/android/security/keystore/KeyGenParameterSpec.java
@@ -59,6 +59,14 @@ import javax.security.auth.x500.X500Principal;
  * of the certificate can be customized in this spec. The self-signed certificate may be replaced at
  * a later time by a certificate signed by a Certificate Authority (CA).
  *
+ * <p>NOTE: If a private key is not authorized to sign the self-signed certificate, then the
+ * certificate will be created with an invalid signature which will not verify. Such a certificate
+ * is still useful because it provides access to the public key. To generate a valid
+ * signature for the certificate the key needs to be authorized for
+ * {@link KeyProperties#PURPOSE_SIGN}, a suitable digest or {@link KeyProperties#DIGEST_NONE}, and
+ * {@link KeyProperties#SIGNATURE_PADDING_RSA_PKCS1} or
+ * {@link KeyProperties#ENCRYPTION_PADDING_NONE}.
+ *
  * <p>NOTE: The key material of the generated symmetric and private keys is not accessible. The key
  * material of the public keys is accessible.
  *
diff --git a/keystore/java/android/security/keystore/KeyProperties.java b/keystore/java/android/security/keystore/KeyProperties.java
index 403e814..f9fe176 100644
--- a/keystore/java/android/security/keystore/KeyProperties.java
+++ b/keystore/java/android/security/keystore/KeyProperties.java
@@ -370,7 +370,7 @@ 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.
+     * any padding scheme, both for encryption and signing.
      */
     public static final String ENCRYPTION_PADDING_NONE = "NoPadding";