Link to magic constants used by AndroidKeyStore API.

This updates the Javadocs of AndroidKeyStore methods which take
constants defined in KeyStoreKeyProperties to contain a link to
the corresponding set of constants and an example of a couple of
accepted constants, to make it easier to understand and find out
what constants to use.

Bug: 18088752
Change-Id: I338134ef136db62a7caca782cb59dbebdc996670

1 files changed, 43 insertions, 17 deletions

diff --git a/keystore/java/android/security/KeyStoreParameter.java b/keystore/java/android/security/KeyStoreParameter.java
index 4a736c33f615..9369f5ba5a78 100644
--- a/keystore/java/android/security/KeyStoreParameter.java
+++ b/keystore/java/android/security/KeyStoreParameter.java
@@ -211,14 +211,20 @@ public final class KeyStoreParameter implements ProtectionParameter {
     }
 
     /**
-     * Gets the set of purposes for which the key can be used.
+     * Gets the set of purposes (e.g., {@code ENCRYPT}, {@code DECRYPT}, {@code SIGN}) for which the
+     * key can be used.
+     *
+     * @see KeyStoreKeyProperties.Purpose
      */
     public @KeyStoreKeyProperties.PurposeEnum int getPurposes() {
         return mPurposes;
     }
 
     /**
-     * Gets the set of padding schemes with which the key can be used when encrypting/decrypting.
+     * Gets the set of padding schemes (e.g., {@code PKCS7Padding}, {@code NoPadding}) with which
+     * the key can be used when encrypting/decrypting.
+     *
+     * @see KeyStoreKeyProperties.EncryptionPadding
      */
     @NonNull
     public @KeyStoreKeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
@@ -226,8 +232,10 @@ public final class KeyStoreParameter implements ProtectionParameter {
     }
 
     /**
-     * Gets the set of padding schemes with which the key can be used when signing or verifying
-     * signatures.
+     * Gets the set of padding schemes (e.g., {@code PSS}) with which the key can be used when
+     * signing or verifying signatures.
+     *
+     * @see KeyStoreKeyProperties.SignaturePadding
      */
     @NonNull
     public @KeyStoreKeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
@@ -235,11 +243,13 @@ public final class KeyStoreParameter implements ProtectionParameter {
     }
 
     /**
-     * Gets the set of digest algorithms with which the key can be used.
+     * Gets the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which the key
+     * can be used.
      *
      * @throws IllegalStateException if this set has not been specified.
      *
      * @see #isDigestsSpecified()
+     * @see KeyStoreKeyProperties.Digest
      */
     @NonNull
     public @KeyStoreKeyProperties.DigestEnum String[] getDigests() {
@@ -261,7 +271,9 @@ public final class KeyStoreParameter implements ProtectionParameter {
     }
 
     /**
-     * Gets the set of block modes with which the key can be used.
+     * Gets the set of block modes (e.g., {@code CBC}, {@code CTR}) with which the key can be used.
+     *
+     * @see KeyStoreKeyProperties.BlockMode
      */
     @NonNull
     public @KeyStoreKeyProperties.BlockModeEnum String[] getBlockModes() {
@@ -436,11 +448,14 @@ public final class KeyStoreParameter implements ProtectionParameter {
         }
 
         /**
-         * Sets the set of purposes for which the key can be used.
+         * Sets the set of purposes (e.g., {@code ENCRYPT}, {@code DECRYPT}, {@code SIGN}) for which
+         * the key can be used.
          *
          * <p>This must be specified for all keys. There is no default.
          *
          * <p><b>NOTE: This has currently no effect on asymmetric key pairs.
+         *
+         * @see KeyStoreKeyProperties.Purpose
          */
         @NonNull
         public Builder setPurposes(@KeyStoreKeyProperties.PurposeEnum int purposes) {
@@ -449,13 +464,15 @@ public final class KeyStoreParameter implements ProtectionParameter {
         }
 
         /**
-         * Sets the set of padding schemes with which the key can be used when
-         * encrypting/decrypting. Attempts to use the key with any other padding scheme will be
-         * rejected.
+         * Sets the set of padding schemes (e.g., {@code PKCS7Padding}, {@code NoPadding}) with
+         * which the key can be used when encrypting/decrypting. Attempts to use the key with any
+         * other padding scheme will be rejected.
          *
          * <p>This must be specified for keys which are used for encryption/decryption.
          *
          * <p><b>NOTE: This has currently no effect on asymmetric key pairs.
+         *
+         * @see KeyStoreKeyProperties.EncryptionPadding
          */
         @NonNull
         public Builder setEncryptionPaddings(
@@ -465,13 +482,15 @@ public final class KeyStoreParameter implements ProtectionParameter {
         }
 
         /**
-         * Sets the set of padding schemes with which the key can be used when
+         * Sets the set of padding schemes (e.g., {@code PSS}) with which the key can be used when
          * signing/verifying. Attempts to use the key with any other padding scheme will be
          * rejected.
          *
          * <p>This must be specified for RSA keys which are used for signing/verification.
          *
          * <p><b>NOTE: This has currently no effect on asymmetric key pairs.
+         *
+         * @see KeyStoreKeyProperties.SignaturePadding
          */
         @NonNull
         public Builder setSignaturePaddings(
@@ -482,13 +501,17 @@ public final class KeyStoreParameter implements ProtectionParameter {
 
 
         /**
-         * Sets the set of digests with which the key can be used when signing/verifying or
-         * generating MACs. Attempts to use the key with any other digest will be rejected.
+         * Sets the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which the
+         * key can be used when signing/verifying or generating MACs. Attempts to use the key with
+         * any other digest algorithm will be rejected.
          *
-         * <p>For HMAC keys, the default is the digest specified in {@link Key#getAlgorithm()}. For
-         * asymmetric signing keys this constraint must be specified.
+         * <p>For HMAC keys, the default is the digest algorithm specified in
+         * {@link Key#getAlgorithm()}. For asymmetric signing keys the set of digest algorithms
+         * must be specified.
          *
          * <p><b>NOTE: This has currently no effect on asymmetric key pairs.
+         *
+         * @see KeyStoreKeyProperties.Digest
          */
         @NonNull
         public Builder setDigests(@KeyStoreKeyProperties.DigestEnum String... digests) {
@@ -497,12 +520,15 @@ public final class KeyStoreParameter implements ProtectionParameter {
         }
 
         /**
-         * Sets the set of block modes with which the key can be used when encrypting/decrypting.
-         * Attempts to use the key with any other block modes will be rejected.
+         * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}) with which the key can be
+         * used when encrypting/decrypting. Attempts to use the key with any other block modes will
+         * be rejected.
          *
          * <p>This must be specified for encryption/decryption keys.
          *
          * <p><b>NOTE: This has currently no effect on asymmetric key pairs.
+         *
+         * @see KeyStoreKeyProperties.BlockMode
          */
         @NonNull
         public Builder setBlockModes(@KeyStoreKeyProperties.BlockModeEnum String... blockModes) {