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
diff --git a/keystore/java/android/security/KeyGeneratorSpec.java b/keystore/java/android/security/KeyGeneratorSpec.java
index 404f939..3849fae 100644
--- a/keystore/java/android/security/KeyGeneratorSpec.java
+++ b/keystore/java/android/security/KeyGeneratorSpec.java
@@ -192,14 +192,20 @@
}
/**
- * 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() {
@@ -207,7 +213,9 @@
}
/**
- * 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() {
@@ -386,9 +394,12 @@
}
/**
- * 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.
+ *
+ * @see KeyStoreKeyProperties.Purpose
*/
@NonNull
public Builder setPurposes(@KeyStoreKeyProperties.PurposeEnum int purposes) {
@@ -397,11 +408,13 @@
}
/**
- * 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.
+ *
+ * @see KeyStoreKeyProperties.EncryptionPadding
*/
@NonNull
public Builder setEncryptionPaddings(
@@ -411,10 +424,13 @@
}
/**
- * 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.
+ *
+ * @see KeyStoreKeyProperties.BlockMode
*/
@NonNull
public Builder setBlockModes(@KeyStoreKeyProperties.BlockModeEnum String... blockModes) {
diff --git a/keystore/java/android/security/KeyPairGeneratorSpec.java b/keystore/java/android/security/KeyPairGeneratorSpec.java
index 2086ccb..08af16c 100644
--- a/keystore/java/android/security/KeyPairGeneratorSpec.java
+++ b/keystore/java/android/security/KeyPairGeneratorSpec.java
@@ -395,14 +395,20 @@
}
/**
- * 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 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.
+ *
+ * @see KeyStoreKeyProperties.Digest
*/
@NonNull
public @KeyStoreKeyProperties.DigestEnum String[] getDigests() {
@@ -410,7 +416,10 @@
}
/**
- * 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 PKCS1Padding}, {@code NoPadding}) with which
+ * the key can be used when encrypting/decrypting.
+ *
+ * @see KeyStoreKeyProperties.EncryptionPadding
*/
@NonNull
public @KeyStoreKeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
@@ -418,7 +427,10 @@
}
/**
- * Gets the set of padding schemes with which the key can be used when signing/verifying.
+ * Gets the set of padding schemes (e.g., {@code PSS}) with which the key can be used when
+ * signing/verifying.
+ *
+ * @see KeyStoreKeyProperties.SignaturePadding
*/
@NonNull
public @KeyStoreKeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
@@ -426,7 +438,9 @@
}
/**
- * 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() {
@@ -759,7 +773,8 @@
}
/**
- * 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.
*
@@ -770,6 +785,8 @@
* Android KeyStore.
*
* <p><b>NOTE: This has currently no effect.
+ *
+ * @see KeyStoreKeyProperties.Purpose
*/
@NonNull
public Builder setPurposes(@KeyStoreKeyProperties.PurposeEnum int purposes) {
@@ -778,12 +795,15 @@
}
/**
- * Sets the set of digests with which the key can be used when signing/verifying. Attempts
- * to use the key with any other digest will be rejected.
+ * Sets the set of digests algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which
+ * the key can be used when signing/verifying. Attempts to use the key with any other digest
+ * algorithm will be rejected.
*
* <p>This must be specified for keys which are used for signing/verification.
*
* <p><b>NOTE: This has currently no effect.
+ *
+ * @see KeyStoreKeyProperties.Digest
*/
@NonNull
public Builder setDigests(@KeyStoreKeyProperties.DigestEnum String... digests) {
@@ -792,13 +812,15 @@
}
/**
- * 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 PKCS1Padding}, {@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.
+ *
+ * @see KeyStoreKeyProperties.EncryptionPadding
*/
@NonNull
public Builder setEncryptionPaddings(
@@ -808,13 +830,15 @@
}
/**
- * 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.
+ *
+ * @see KeyStoreKeyProperties.SignaturePadding
*/
@NonNull
public Builder setSignaturePaddings(
@@ -824,12 +848,15 @@
}
/**
- * 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.
+ *
+ * @see KeyStoreKeyProperties.BlockMode
*/
@NonNull
public Builder setBlockModes(@KeyStoreKeyProperties.BlockModeEnum String... blockModes) {
diff --git a/keystore/java/android/security/KeyStoreKeySpec.java b/keystore/java/android/security/KeyStoreKeySpec.java
index 81a19bb..acd6404 100644
--- a/keystore/java/android/security/KeyStoreKeySpec.java
+++ b/keystore/java/android/security/KeyStoreKeySpec.java
@@ -179,14 +179,19 @@
}
/**
- * 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 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() {
@@ -194,7 +199,10 @@
}
/**
- * Gets the set of padding modes 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() {
@@ -202,7 +210,10 @@
}
/**
- * Gets the set of padding modes with which the key can be used when signing/verifying.
+ * Gets the set of padding schemes (e.g., {@code PSS}) with which the key can be used when
+ * signing/verifying.
+ *
+ * @see KeyStoreKeyProperties.SignaturePadding
*/
@NonNull
public @KeyStoreKeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
@@ -210,7 +221,10 @@
}
/**
- * 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.
+ *
+ * @see KeyStoreKeyProperties.Digest
*/
@NonNull
public @KeyStoreKeyProperties.DigestEnum String[] getDigests() {
diff --git a/keystore/java/android/security/KeyStoreParameter.java b/keystore/java/android/security/KeyStoreParameter.java
index 4a736c3..9369f5b 100644
--- a/keystore/java/android/security/KeyStoreParameter.java
+++ b/keystore/java/android/security/KeyStoreParameter.java
@@ -211,14 +211,20 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
}
/**
- * 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 @@
/**
- * 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 @@
}
/**
- * 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) {