To generate the key, use a {@link javax.crypto.KeyGenerator} with - {@link android.security.KeyGeneratorSpec}. + {@link android.security.keystore.KeyGenParameterSpec}.
+ * After generation, the {@code keyStoreAlias} is used with the + * {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter)} + * interface to retrieve the {@link PrivateKey} and its associated + * {@link Certificate} chain. + *
+ * The KeyPair generator will create a self-signed certificate with the subject + * as its X.509v3 Subject Distinguished Name and as its X.509v3 Issuer + * Distinguished Name along with the other parameters specified with the + * {@link Builder}. + *
+ * The self-signed X.509 certificate may be replaced at a later time by a + * certificate signed by a real Certificate Authority. * - *
To generate a key pair, create an instance of this class using the {@link Builder}, initialize - * a {@code KeyPairGenerator} of the desired key type (e.g., {@code EC} or {@code RSA}) from the - * {@code AndroidKeyStore} provider with the {@code KeyPairGeneratorSpec} instance, and then - * generate a key pair using {@link KeyPairGenerator#generateKeyPair()}. - * - *
The generated key pair will be returned by the {@code KeyPairGenerator} and also stored in the - * Android KeyStore under the alias specified in this {@code KeyPairGeneratorSpec}. To obtain the - * private key from the Android KeyStore use - * {@link java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null)} or - * {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)}. - * To obtain the public key from the Android KeyStore use - * {@link java.security.KeyStore#getCertificate(String)} and then - * {@link Certificate#getPublicKey()}. - * - *
A self-signed X.509 certificate will be also generated and stored in the Android KeyStore. - * This is because the {@link java.security.KeyStore} abstraction does not support storing key pairs - * without a certificate. The subject, serial number, and validity dates of the certificate can be - * specified in this {@code KeyPairGeneratorSpec}. The self-signed certificate may be replaced at a - * later time by a certificate signed by a Certificate Authority (CA). - * - *
NOTE: The key material of the private keys generating using the {@code KeyPairGeneratorSpec} - * is not accessible. The key material of the public keys is accessible. - * - *
{@code
- * KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
- * KeyStoreKeyProperties.KEY_ALGORITHM_EC,
- * "AndroidKeyStore");
- * keyPairGenerator.initialize(
- * new KeyGeneratorSpec.Builder(context)
- * .setAlias("key2")
- * .setPurposes(KeyStoreKeyProperties.PURPOSE_SIGN
- * | KeyStoreKeyProperties.PURPOSE_VERIFY)
- * .setDigests(KeyStoreKeyProperties.DIGEST_SHA256
- * | KeyStoreKeyProperties.DIGEST_SHA384
- * | KeyStoreKeyProperties.DIGEST_SHA512)
- * // Only permit this key to be used if the user authenticated
- * // within the last five minutes.
- * .setUserAuthenticationRequired(true)
- * .setUserAuthenticationValidityDurationSeconds(5 * 60)
- * .build());
- * KeyPair keyPair = keyPairGenerator.generateKey();
- *
- * // The key pair can also be obtained from the Android KeyStore any time as follows:
- * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
- * keyStore.load(null);
- * PrivateKey privateKey = (PrivateKey) keyStore.getKey("key2", null);
- * PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey();
- * }
+ * @deprecated Use {@link KeyGenParameterSpec} instead.
*/
+@Deprecated
public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
- private static final X500Principal DEFAULT_CERT_SUBJECT = new X500Principal("CN=fake");
- private static final BigInteger DEFAULT_CERT_SERIAL_NUMBER = new BigInteger("1");
- private static final Date DEFAULT_CERT_NOT_BEFORE = new Date(0L); // Jan 1 1970
- private static final Date DEFAULT_CERT_NOT_AFTER = new Date(2461449600000L); // Jan 1 2048
-
private final Context mContext;
private final String mKeystoreAlias;
@@ -120,28 +80,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
private final int mFlags;
- private final Date mKeyValidityStart;
-
- private final Date mKeyValidityForOriginationEnd;
-
- private final Date mKeyValidityForConsumptionEnd;
-
- private final @KeyStoreKeyProperties.PurposeEnum int mPurposes;
-
- private final @KeyStoreKeyProperties.DigestEnum String[] mDigests;
-
- private final @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
-
- private final @KeyStoreKeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
-
- private final @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes;
-
- private final boolean mRandomizedEncryptionRequired;
-
- private final boolean mUserAuthenticationRequired;
-
- private final int mUserAuthenticationValidityDurationSeconds;
-
/**
* Parameter specification for the "{@code AndroidKeyPairGenerator}"
* instance of the {@link java.security.KeyPairGenerator} API. The
@@ -162,7 +100,7 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
* @param context Android context for the activity
* @param keyStoreAlias name to use for the generated key in the Android
* keystore
- * @param keyType key algorithm to use (EC, RSA)
+ * @param keyType key algorithm to use (RSA, DSA, EC)
* @param keySize size of key to generate
* @param spec the underlying key type parameters
* @param subjectDN X.509 v3 Subject Distinguished Name
@@ -176,39 +114,21 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
*/
public KeyPairGeneratorSpec(Context context, String keyStoreAlias, String keyType, int keySize,
AlgorithmParameterSpec spec, X500Principal subjectDN, BigInteger serialNumber,
- Date startDate, Date endDate, int flags,
- Date keyValidityStart,
- Date keyValidityForOriginationEnd,
- Date keyValidityForConsumptionEnd,
- @KeyStoreKeyProperties.PurposeEnum int purposes,
- @KeyStoreKeyProperties.DigestEnum String[] digests,
- @KeyStoreKeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
- @KeyStoreKeyProperties.SignaturePaddingEnum String[] signaturePaddings,
- @KeyStoreKeyProperties.BlockModeEnum String[] blockModes,
- boolean randomizedEncryptionRequired,
- boolean userAuthenticationRequired,
- int userAuthenticationValidityDurationSeconds) {
+ Date startDate, Date endDate, int flags) {
if (context == null) {
throw new IllegalArgumentException("context == null");
} else if (TextUtils.isEmpty(keyStoreAlias)) {
throw new IllegalArgumentException("keyStoreAlias must not be empty");
- } else if ((userAuthenticationValidityDurationSeconds < 0)
- && (userAuthenticationValidityDurationSeconds != -1)) {
- throw new IllegalArgumentException(
- "userAuthenticationValidityDurationSeconds must not be negative");
- }
-
- if (subjectDN == null) {
- subjectDN = DEFAULT_CERT_SUBJECT;
- }
- if (startDate == null) {
- startDate = DEFAULT_CERT_NOT_BEFORE;
- }
- if (endDate == null) {
- endDate = DEFAULT_CERT_NOT_AFTER;
- }
- if (serialNumber == null) {
- serialNumber = DEFAULT_CERT_SERIAL_NUMBER;
+ } else if (subjectDN == null) {
+ throw new IllegalArgumentException("subjectDN == null");
+ } else if (serialNumber == null) {
+ throw new IllegalArgumentException("serialNumber == null");
+ } else if (startDate == null) {
+ throw new IllegalArgumentException("startDate == null");
+ } else if (endDate == null) {
+ throw new IllegalArgumentException("endDate == null");
+ } else if (endDate.before(startDate)) {
+ throw new IllegalArgumentException("endDate < startDate");
}
if (endDate.before(startDate)) {
@@ -225,50 +145,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
mStartDate = startDate;
mEndDate = endDate;
mFlags = flags;
- mKeyValidityStart = keyValidityStart;
- mKeyValidityForOriginationEnd = keyValidityForOriginationEnd;
- mKeyValidityForConsumptionEnd = keyValidityForConsumptionEnd;
- mPurposes = purposes;
- mDigests = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(digests));
- mEncryptionPaddings =
- ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(encryptionPaddings));
- mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(signaturePaddings));
- mBlockModes = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(blockModes));
- mRandomizedEncryptionRequired = randomizedEncryptionRequired;
- mUserAuthenticationRequired = userAuthenticationRequired;
- mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
- }
-
- /**
- * TODO: Remove this constructor once tests are switched over to the new one above.
- * @hide
- */
- public KeyPairGeneratorSpec(Context context, String keyStoreAlias, String keyType, int keySize,
- AlgorithmParameterSpec spec, X500Principal subjectDN, BigInteger serialNumber,
- Date startDate, Date endDate, int flags) {
-
- this(context,
- keyStoreAlias,
- keyType,
- keySize,
- spec,
- subjectDN,
- serialNumber,
- startDate,
- endDate,
- flags,
- startDate,
- endDate,
- endDate,
- 0, // purposes
- null, // digests
- null, // encryption paddings
- null, // signature paddings
- null, // block modes
- false, // randomized encryption required
- false, // user authentication required
- -1 // user authentication validity duration (seconds)
- );
}
/**
@@ -288,10 +164,10 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
/**
* Returns the type of key pair (e.g., {@code EC}, {@code RSA}) to be generated. See
- * {@link KeyStoreKeyProperties}.{@code KEY_ALGORITHM} constants.
+ * {@link KeyProperties}.{@code KEY_ALGORITHM} constants.
*/
@Nullable
- public @KeyStoreKeyProperties.KeyAlgorithmEnum String getKeyType() {
+ public @KeyProperties.KeyAlgorithmEnum String getKeyType() {
return mKeyType;
}
@@ -352,147 +228,26 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec {
/**
* @hide
*/
- int getFlags() {
+ public int getFlags() {
return mFlags;
}
/**
* Returns {@code true} if the key must be encrypted at rest. This will protect the key pair
* with the secure lock screen credential (e.g., password, PIN, or pattern).
+ *
+ * Note that encrypting the key at rest requires that the secure lock screen (e.g., password, + * PIN, pattern) is set up, otherwise key generation will fail. Moreover, this key will be + * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device + * Administrator). Finally, this key cannot be used until the user unlocks the secure lock + * screen after boot. + * + * @see KeyguardManager#isDeviceSecure() */ public boolean isEncryptionRequired() { return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0; } - /** - * Gets the time instant before which the key pair is not yet valid. - * - * @return instant or {@code null} if not restricted. - */ - @Nullable - public Date getKeyValidityStart() { - return mKeyValidityStart; - } - - /** - * Gets the time instant after which the key pair is no longer valid for decryption and - * verification. - * - * @return instant or {@code null} if not restricted. - */ - @Nullable - public Date getKeyValidityForConsumptionEnd() { - return mKeyValidityForConsumptionEnd; - } - - /** - * Gets the time instant after which the key pair is no longer valid for encryption and signing. - * - * @return instant or {@code null} if not restricted. - */ - @Nullable - public Date getKeyValidityForOriginationEnd() { - return mKeyValidityForOriginationEnd; - } - - /** - * Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used. - * Attempts to use the key for any other purpose will be rejected. - * - *
See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags. - */ - public @KeyStoreKeyProperties.PurposeEnum int getPurposes() { - return mPurposes; - } - - /** - * 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() { - return ArrayUtils.cloneIfNotEmpty(mDigests); - } - - /** - * Gets the set of padding schemes (e.g., {@code OEAPPadding}, {@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. - * - *
See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants. - */ - @NonNull - public @KeyStoreKeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() { - return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings); - } - - /** - * Gets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key - * can be used when signing/verifying. Attempts to use the key with any other padding scheme - * will be rejected. - * - *
See {@link KeyStoreKeyProperties}.{@code SIGNATURE_PADDING} constants. - */ - @NonNull - public @KeyStoreKeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() { - return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings); - } - - /** - * Gets 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. - * - *
See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants. - */ - @NonNull - public @KeyStoreKeyProperties.BlockModeEnum String[] getBlockModes() { - return ArrayUtils.cloneIfNotEmpty(mBlockModes); - } - - /** - * Returns {@code true} if encryption using this key must be sufficiently randomized to produce - * different ciphertexts for the same plaintext every time. The formal cryptographic property - * being required is indistinguishability under chosen-plaintext attack ({@code - * IND-CPA}). This property is important because it mitigates several classes of - * weaknesses due to which ciphertext may leak information about plaintext. For example, if a - * given plaintext always produces the same ciphertext, an attacker may see the repeated - * ciphertexts and be able to deduce something about the plaintext. - */ - public boolean isRandomizedEncryptionRequired() { - return mRandomizedEncryptionRequired; - } - - /** - * Returns {@code true} if user authentication is required for this key to be used. - * - *
This restriction applies only to private key operations. Public key operations are not - * restricted. - * - * @see #getUserAuthenticationValidityDurationSeconds() - */ - public boolean isUserAuthenticationRequired() { - return mUserAuthenticationRequired; - } - - /** - * Gets the duration of time (seconds) for which this key can be used after the user is - * successfully authenticated. This has effect only if user authentication is required. - * - *
This restriction applies only to private key operations. Public key operations are not - * restricted. - * - * @return duration in seconds or {@code -1} if authentication is required for every use of the - * key. - * - * @see #isUserAuthenticationRequired() - */ - public int getUserAuthenticationValidityDurationSeconds() { - return mUserAuthenticationValidityDurationSeconds; - } - /** * Builder class for {@link KeyPairGeneratorSpec} objects. *
@@ -513,7 +268,10 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { * .setSubject(new X500Principal("CN=myKey")).setSerial(BigInteger.valueOf(1337)) * .setStartDate(start.getTime()).setEndDate(end.getTime()).build(); * + * + * @deprecated Use {@link KeyGenParameterSpec.Builder} instead. */ + @Deprecated public final static class Builder { private final Context mContext; @@ -535,28 +293,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { private int mFlags; - private Date mKeyValidityStart; - - private Date mKeyValidityForOriginationEnd; - - private Date mKeyValidityForConsumptionEnd; - - private @KeyStoreKeyProperties.PurposeEnum int mPurposes; - - private @KeyStoreKeyProperties.DigestEnum String[] mDigests; - - private @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings; - - private @KeyStoreKeyProperties.SignaturePaddingEnum String[] mSignaturePaddings; - - private @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes; - - private boolean mRandomizedEncryptionRequired = true; - - private boolean mUserAuthenticationRequired; - - private int mUserAuthenticationValidityDurationSeconds = -1; - /** * Creates a new instance of the {@code Builder} with the given * {@code context}. The {@code context} passed in may be used to pop up @@ -586,11 +322,11 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { /** * Sets the type of key pair (e.g., {@code EC}, {@code RSA}) of the key pair to be - * generated. See {@link KeyStoreKeyProperties}.{@code KEY_ALGORITHM} constants. + * generated. See {@link KeyProperties}.{@code KEY_ALGORITHM} constants. * */ @NonNull - public Builder setKeyType(@NonNull @KeyStoreKeyProperties.KeyAlgorithmEnum String keyType) + public Builder setKeyType(@NonNull @KeyProperties.KeyAlgorithmEnum String keyType) throws NoSuchAlgorithmException { if (keyType == null) { throw new NullPointerException("keyType == null"); @@ -632,10 +368,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { /** * Sets the subject used for the self-signed certificate of the * generated key pair. - * - *
The subject must be specified on API Level - * {@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1 LOLLIPOP_MR1} and older platforms. On - * newer platforms the subject defaults to {@code CN=fake} if not specified. */ @NonNull public Builder setSubject(@NonNull X500Principal subject) { @@ -649,10 +381,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { /** * Sets the serial number used for the self-signed certificate of the * generated key pair. - * - *
The serial number must be specified on API Level - * {@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1 LOLLIPOP_MR1} and older platforms. On - * newer platforms the serial number defaults to {@code 1} if not specified. */ @NonNull public Builder setSerialNumber(@NonNull BigInteger serialNumber) { @@ -666,10 +394,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { /** * Sets the start of the validity period for the self-signed certificate * of the generated key pair. - * - *
The date must be specified on API Level - * {@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1 LOLLIPOP_MR1} and older platforms. On - * newer platforms the date defaults to {@code Jan 1 1970} if not specified. */ @NonNull public Builder setStartDate(@NonNull Date startDate) { @@ -683,10 +407,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { /** * Sets the end of the validity period for the self-signed certificate * of the generated key pair. - * - *
The date must be specified on API Level - * {@link android.os.Build.VERSION_CODES#LOLLIPOP_MR1 LOLLIPOP_MR1} and older platforms. On - * newer platforms the date defaults to {@code Jan 1 2048} if not specified. */ @NonNull public Builder setEndDate(@NonNull Date endDate) { @@ -715,239 +435,6 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { return this; } - /** - * Sets the time instant before which the key is not yet valid. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect. - * - * @see #setKeyValidityEnd(Date) - */ - @NonNull - public Builder setKeyValidityStart(Date startDate) { - mKeyValidityStart = startDate; - return this; - } - - /** - * Sets the time instant after which the key is no longer valid. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect. - * - * @see #setKeyValidityStart(Date) - * @see #setKeyValidityForConsumptionEnd(Date) - * @see #setKeyValidityForOriginationEnd(Date) - */ - @NonNull - public Builder setKeyValidityEnd(Date endDate) { - setKeyValidityForOriginationEnd(endDate); - setKeyValidityForConsumptionEnd(endDate); - return this; - } - - /** - * Sets the time instant after which the key is no longer valid for encryption and signing. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect. - * - * @see #setKeyValidityForConsumptionEnd(Date) - */ - @NonNull - public Builder setKeyValidityForOriginationEnd(Date endDate) { - mKeyValidityForOriginationEnd = endDate; - return this; - } - - /** - * Sets the time instant after which the key is no longer valid for decryption and - * verification. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect. - * - * @see #setKeyValidityForOriginationEnd(Date) - */ - @NonNull - public Builder setKeyValidityForConsumptionEnd(Date endDate) { - mKeyValidityForConsumptionEnd = endDate; - return this; - } - - /** - * Sets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used. - * Attempts to use the key for any other purpose will be rejected. - * - *
This must be specified for all keys. There is no default. - * - *
If the set of purposes for which the key can be used does not contain - * {@link KeyStoreKeyProperties#PURPOSE_SIGN}, the self-signed certificate generated by - * {@link KeyPairGenerator} of {@code AndroidKeyStore} provider will contain an invalid - * signature. This is OK if the certificate is only used for obtaining the public key from - * Android KeyStore. - * - *
NOTE: This has currently no effect. - * - *
See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags. - */ - @NonNull - public Builder setPurposes(@KeyStoreKeyProperties.PurposeEnum int purposes) { - mPurposes = purposes; - return this; - } - - /** - * 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. - * - *
This must be specified for keys which are used for signing/verification. - * - *
NOTE: This has currently no effect. - * - * @see KeyStoreKeyProperties.Digest - */ - @NonNull - public Builder setDigests(@KeyStoreKeyProperties.DigestEnum String... digests) { - mDigests = ArrayUtils.cloneIfNotEmpty(digests); - return this; - } - - /** - * Sets the set of padding schemes (e.g., {@code OAEPPadding}, {@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. - * - *
This must be specified for keys which are used for encryption/decryption. - * - *
NOTE: This has currently no effect. - * - *
See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants. - */ - @NonNull - public Builder setEncryptionPaddings( - @KeyStoreKeyProperties.EncryptionPaddingEnum String... paddings) { - mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(paddings); - return this; - } - - /** - * Sets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key - * can be used when signing/verifying. Attempts to use the key with any other padding scheme - * will be rejected. - * - *
This must be specified for RSA keys which are used for signing/verification. - * - *
NOTE: This has currently no effect. - * - *
See {@link KeyStoreKeyProperties}.{@code SIGNATURE_PADDING} constants. - */ - @NonNull - public Builder setSignaturePaddings( - @KeyStoreKeyProperties.SignaturePaddingEnum String... paddings) { - mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(paddings); - return this; - } - - /** - * Sets the set of block modes (e.g., {@code ECB}, {@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. - * - *
This must be specified for encryption/decryption keys. - * - *
NOTE: This has currently no effect. - * - *
See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants. - */ - @NonNull - public Builder setBlockModes(@KeyStoreKeyProperties.BlockModeEnum String... blockModes) { - mBlockModes = ArrayUtils.cloneIfNotEmpty(blockModes); - return this; - } - - /** - * Sets whether encryption using this key must be sufficiently randomized to produce - * different ciphertexts for the same plaintext every time. The formal cryptographic - * property being required is indistinguishability under chosen-plaintext attack - * ({@code IND-CPA}). This property is important because it mitigates several classes - * of weaknesses due to which ciphertext may leak information about plaintext. For example, - * if a given plaintext always produces the same ciphertext, an attacker may see the - * repeated ciphertexts and be able to deduce something about the plaintext. - * - *
By default, {@code IND-CPA} is required. - * - *
When {@code IND-CPA} is required, encryption/decryption transformations which do not - * offer {@code IND-CPA}, such as RSA without padding, are prohibited. - * - *
Before disabling this requirement, consider the following approaches instead: - *
NOTE: This has currently no effect. - */ - @NonNull - public Builder setRandomizedEncryptionRequired(boolean required) { - mRandomizedEncryptionRequired = required; - return this; - } - - /** - * Sets whether user authentication is required to use this key. - * - *
By default, the key can be used without user authentication. - * - *
When user authentication is required, the user authorizes the use of the key by - * authenticating to this Android device using a subset of their secure lock screen - * credentials. Different authentication methods are used depending on whether the every - * use of the key must be authenticated (as specified by - * {@link #setUserAuthenticationValidityDurationSeconds(int)}). - * More - * information. - * - *
This restriction applies only to private key operations. Public key operations are not - * restricted. - * - *
NOTE: This has currently no effect. - * - * @see #setUserAuthenticationValidityDurationSeconds(int) - */ - @NonNull - public Builder setUserAuthenticationRequired(boolean required) { - mUserAuthenticationRequired = required; - return this; - } - - /** - * Sets the duration of time (seconds) for which this key can be used after the user is - * successfully authenticated. This has effect only if user authentication is required. - * - *
By default, the user needs to authenticate for every use of the key. - * - *
This restriction applies only to private key operations. Public key operations are not - * restricted. - * - *
NOTE: This has currently no effect. - * - * @param seconds duration in seconds or {@code -1} if the user needs to authenticate for - * every use of the key. - * - * @see #setUserAuthenticationRequired(boolean) - */ - @NonNull - public Builder setUserAuthenticationValidityDurationSeconds( - @IntRange(from = -1) int seconds) { - mUserAuthenticationValidityDurationSeconds = seconds; - return this; - } - /** * Builds the instance of the {@code KeyPairGeneratorSpec}. * @@ -965,18 +452,7 @@ public final class KeyPairGeneratorSpec implements AlgorithmParameterSpec { mSerialNumber, mStartDate, mEndDate, - mFlags, - mKeyValidityStart, - mKeyValidityForOriginationEnd, - mKeyValidityForConsumptionEnd, - mPurposes, - mDigests, - mEncryptionPaddings, - mSignaturePaddings, - mBlockModes, - mRandomizedEncryptionRequired, - mUserAuthenticationRequired, - mUserAuthenticationValidityDurationSeconds); + mFlags); } } } diff --git a/keystore/java/android/security/KeyStore.java b/keystore/java/android/security/KeyStore.java index caa4fec4548eb..72c74dffc448d 100644 --- a/keystore/java/android/security/KeyStore.java +++ b/keystore/java/android/security/KeyStore.java @@ -35,6 +35,11 @@ import android.security.keymaster.KeymasterArguments; import android.security.keymaster.KeymasterBlob; import android.security.keymaster.KeymasterDefs; import android.security.keymaster.OperationResult; +import android.security.keystore.KeyExpiredException; +import android.security.keystore.KeyNotYetValidException; +import android.security.keystore.KeyPermanentlyInvalidatedException; +import android.security.keystore.KeyProperties; +import android.security.keystore.UserNotAuthenticatedException; import android.util.Log; import java.security.InvalidKeyException; @@ -101,10 +106,10 @@ public class KeyStore { private KeyStore(IKeystoreService binder) { mBinder = binder; - mContext = getContext(); + mContext = getApplicationContext(); } - private static Context getContext() { + static Context getApplicationContext() { ActivityThread activityThread = ActivityThread.currentActivityThread(); if (activityThread == null) { throw new IllegalStateException( @@ -131,10 +136,10 @@ public class KeyStore { return mToken; } - static int getKeyTypeForAlgorithm(@KeyStoreKeyProperties.KeyAlgorithmEnum String keyType) { - if (KeyStoreKeyProperties.KEY_ALGORITHM_RSA.equalsIgnoreCase(keyType)) { + static int getKeyTypeForAlgorithm(@KeyProperties.KeyAlgorithmEnum String keyType) { + if (KeyProperties.KEY_ALGORITHM_RSA.equalsIgnoreCase(keyType)) { return NativeConstants.EVP_PKEY_RSA; - } else if (KeyStoreKeyProperties.KEY_ALGORITHM_EC.equalsIgnoreCase(keyType)) { + } else if (KeyProperties.KEY_ALGORITHM_EC.equalsIgnoreCase(keyType)) { return NativeConstants.EVP_PKEY_EC; } else { return -1; diff --git a/keystore/java/android/security/KeyStoreCipherSpi.java b/keystore/java/android/security/KeyStoreCipherSpi.java index 4eeca47a6b5c1..b0f1695188c2a 100644 --- a/keystore/java/android/security/KeyStoreCipherSpi.java +++ b/keystore/java/android/security/KeyStoreCipherSpi.java @@ -20,6 +20,7 @@ import android.os.IBinder; import android.security.keymaster.KeymasterArguments; import android.security.keymaster.KeymasterDefs; import android.security.keymaster.OperationResult; +import android.security.keystore.KeyProperties; import java.security.AlgorithmParameters; import java.security.GeneralSecurityException; @@ -496,7 +497,7 @@ public abstract class KeyStoreCipherSpi extends CipherSpi implements KeyStoreCry if ((mIv != null) && (mIv.length > 0)) { try { AlgorithmParameters params = - AlgorithmParameters.getInstance(KeyStoreKeyProperties.KEY_ALGORITHM_AES); + AlgorithmParameters.getInstance(KeyProperties.KEY_ALGORITHM_AES); params.init(new IvParameterSpec(mIv)); return params; } catch (NoSuchAlgorithmException e) { diff --git a/keystore/java/android/security/KeyStoreCryptoOperationUtils.java b/keystore/java/android/security/KeyStoreCryptoOperationUtils.java index 311278bab16b8..c9bdd41676dde 100644 --- a/keystore/java/android/security/KeyStoreCryptoOperationUtils.java +++ b/keystore/java/android/security/KeyStoreCryptoOperationUtils.java @@ -17,6 +17,7 @@ package android.security; import android.security.keymaster.KeymasterDefs; +import android.security.keystore.UserNotAuthenticatedException; import java.security.GeneralSecurityException; import java.security.InvalidAlgorithmParameterException; diff --git a/keystore/java/android/security/KeyStoreKeyGeneratorSpi.java b/keystore/java/android/security/KeyStoreKeyGeneratorSpi.java index d734d66d95fde..feec00f7b77b5 100644 --- a/keystore/java/android/security/KeyStoreKeyGeneratorSpi.java +++ b/keystore/java/android/security/KeyStoreKeyGeneratorSpi.java @@ -19,11 +19,16 @@ package android.security; import android.security.keymaster.KeyCharacteristics; import android.security.keymaster.KeymasterArguments; import android.security.keymaster.KeymasterDefs; +import android.security.keystore.KeyGenParameterSpec; +import android.security.keystore.KeyProperties; + +import libcore.util.EmptyArray; import java.security.InvalidAlgorithmParameterException; import java.security.ProviderException; import java.security.SecureRandom; import java.security.spec.AlgorithmParameterSpec; +import java.util.Arrays; import java.util.Date; import javax.crypto.KeyGeneratorSpi; @@ -96,13 +101,14 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { private final int mKeymasterDigest; private final int mDefaultKeySizeBits; - private KeyGeneratorSpec mSpec; + private KeyGenParameterSpec mSpec; private SecureRandom mRng; protected int mKeySizeBits; private int[] mKeymasterPurposes; private int[] mKeymasterBlockModes; private int[] mKeymasterPaddings; + private int[] mKeymasterDigests; protected KeyStoreKeyGeneratorSpi( int keymasterAlgorithm, @@ -129,14 +135,14 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { @Override protected void engineInit(SecureRandom random) { - throw new UnsupportedOperationException("Cannot initialize without an " - + KeyGeneratorSpec.class.getName() + " parameter"); + throw new UnsupportedOperationException("Cannot initialize without a " + + KeyGenParameterSpec.class.getName() + " parameter"); } @Override protected void engineInit(int keySize, SecureRandom random) { throw new UnsupportedOperationException("Cannot initialize without a " - + KeyGeneratorSpec.class.getName() + " parameter"); + + KeyGenParameterSpec.class.getName() + " parameter"); } @Override @@ -146,11 +152,11 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { boolean success = false; try { - if ((params == null) || (!(params instanceof KeyGeneratorSpec))) { - throw new InvalidAlgorithmParameterException("Cannot initialize without an " - + KeyGeneratorSpec.class.getName() + " parameter"); + if ((params == null) || (!(params instanceof KeyGenParameterSpec))) { + throw new InvalidAlgorithmParameterException("Cannot initialize without a " + + KeyGenParameterSpec.class.getName() + " parameter"); } - KeyGeneratorSpec spec = (KeyGeneratorSpec) params; + KeyGenParameterSpec spec = (KeyGenParameterSpec) params; if (spec.getKeystoreAlias() == null) { throw new InvalidAlgorithmParameterException("KeyStore entry alias not provided"); } @@ -168,13 +174,11 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { } try { - mKeymasterPurposes = - KeyStoreKeyProperties.Purpose.allToKeymaster(spec.getPurposes()); - mKeymasterPaddings = KeyStoreKeyProperties.EncryptionPadding.allToKeymaster( + mKeymasterPurposes = KeyProperties.Purpose.allToKeymaster(spec.getPurposes()); + mKeymasterPaddings = KeyProperties.EncryptionPadding.allToKeymaster( spec.getEncryptionPaddings()); - mKeymasterBlockModes = - KeyStoreKeyProperties.BlockMode.allToKeymaster(spec.getBlockModes()); - if (((spec.getPurposes() & KeyStoreKeyProperties.PURPOSE_ENCRYPT) != 0) + mKeymasterBlockModes = KeyProperties.BlockMode.allToKeymaster(spec.getBlockModes()); + if (((spec.getPurposes() & KeyProperties.PURPOSE_ENCRYPT) != 0) && (spec.isRandomizedEncryptionRequired())) { for (int keymasterBlockMode : mKeymasterBlockModes) { if (!KeymasterUtils.isKeymasterBlockModeIndCpaCompatible( @@ -182,14 +186,55 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { throw new InvalidAlgorithmParameterException( "Randomized encryption (IND-CPA) required but may be violated" + " by block mode: " - + KeyStoreKeyProperties.BlockMode.fromKeymaster( - keymasterBlockMode) - + ". See " + KeyGeneratorSpec.class.getName() + + KeyProperties.BlockMode.fromKeymaster(keymasterBlockMode) + + ". See " + KeyGenParameterSpec.class.getName() + " documentation."); } } } - } catch (IllegalArgumentException e) { + if (spec.isDigestsSpecified()) { + // Digest(s) explicitly specified in the spec + mKeymasterDigests = KeyProperties.Digest.allToKeymaster(spec.getDigests()); + if (mKeymasterDigest != -1) { + // Key algorithm implies a digest -- ensure it's specified in the spec as + // first digest. + if (!com.android.internal.util.ArrayUtils.contains( + mKeymasterDigests, mKeymasterDigest)) { + throw new InvalidAlgorithmParameterException( + "Digests specified in algorithm parameters (" + + Arrays.asList(spec.getDigests()) + ") must include " + + " the digest " + + KeyProperties.Digest.fromKeymaster(mKeymasterDigest) + + " implied by key algorithm"); + } + if (mKeymasterDigests[0] != mKeymasterDigest) { + // The first digest is not the one implied by the key algorithm. + // Swap the implied digest with the first one. + for (int i = 0; i < mKeymasterDigests.length; i++) { + if (mKeymasterDigests[i] == mKeymasterDigest) { + mKeymasterDigests[i] = mKeymasterDigests[0]; + mKeymasterDigests[0] = mKeymasterDigest; + break; + } + } + } + } + } else { + // No digest specified in the spec + if (mKeymasterDigest != -1) { + // Key algorithm implies a digest -- use that digest + mKeymasterDigests = new int[] {mKeymasterDigest}; + } else { + mKeymasterDigests = EmptyArray.INT; + } + } + if (mKeymasterAlgorithm == KeymasterDefs.KM_ALGORITHM_HMAC) { + if (mKeymasterDigests.length == 0) { + throw new InvalidAlgorithmParameterException( + "At least one digest algorithm must be specified"); + } + } + } catch (IllegalStateException | IllegalArgumentException e) { throw new InvalidAlgorithmParameterException(e); } @@ -212,29 +257,26 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { @Override protected SecretKey engineGenerateKey() { - KeyGeneratorSpec spec = mSpec; + KeyGenParameterSpec spec = mSpec; if (spec == null) { throw new IllegalStateException("Not initialized"); } - if ((spec.isEncryptionRequired()) + if ((spec.isEncryptionAtRestRequired()) && (mKeyStore.state() != KeyStore.State.UNLOCKED)) { throw new IllegalStateException( - "Android KeyStore must be in initialized and unlocked state if encryption is" - + " required"); + "Requested to import a key which must be encrypted at rest using secure lock" + + " screen credential, but the credential hasn't yet been entered by the user"); } KeymasterArguments args = new KeymasterArguments(); args.addInt(KeymasterDefs.KM_TAG_KEY_SIZE, mKeySizeBits); args.addInt(KeymasterDefs.KM_TAG_ALGORITHM, mKeymasterAlgorithm); - if (mKeymasterDigest != -1) { - args.addInt(KeymasterDefs.KM_TAG_DIGEST, mKeymasterDigest); - } args.addInts(KeymasterDefs.KM_TAG_PURPOSE, mKeymasterPurposes); args.addInts(KeymasterDefs.KM_TAG_BLOCK_MODE, mKeymasterBlockModes); args.addInts(KeymasterDefs.KM_TAG_PADDING, mKeymasterPaddings); + args.addInts(KeymasterDefs.KM_TAG_DIGEST, mKeymasterDigests); KeymasterUtils.addUserAuthArgs(args, - spec.getContext(), spec.isUserAuthenticationRequired(), spec.getUserAuthenticationValidityDurationSeconds()); args.addDate(KeymasterDefs.KM_TAG_ACTIVE_DATETIME, @@ -247,7 +289,7 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { (spec.getKeyValidityForConsumptionEnd() != null) ? spec.getKeyValidityForConsumptionEnd() : new Date(Long.MAX_VALUE)); - if (((spec.getPurposes() & KeyStoreKeyProperties.PURPOSE_ENCRYPT) != 0) + if (((spec.getPurposes() & KeyProperties.PURPOSE_ENCRYPT) != 0) && (!spec.isRandomizedEncryptionRequired())) { // Permit caller-provided IV when encrypting with this key args.addBoolean(KeymasterDefs.KM_TAG_CALLER_NONCE); @@ -265,9 +307,9 @@ public abstract class KeyStoreKeyGeneratorSpi extends KeyGeneratorSpi { throw new ProviderException( "Keystore operation failed", KeyStore.getKeyStoreException(errorCode)); } - @KeyStoreKeyProperties.KeyAlgorithmEnum String keyAlgorithmJCA; + @KeyProperties.KeyAlgorithmEnum String keyAlgorithmJCA; try { - keyAlgorithmJCA = KeyStoreKeyProperties.KeyAlgorithm.fromKeymasterSecretKeyAlgorithm( + keyAlgorithmJCA = KeyProperties.KeyAlgorithm.fromKeymasterSecretKeyAlgorithm( mKeymasterAlgorithm, mKeymasterDigest); } catch (IllegalArgumentException e) { throw new ProviderException("Failed to obtain JCA secret key algorithm name", e); diff --git a/keystore/java/android/security/KeyStoreParameter.java b/keystore/java/android/security/KeyStoreParameter.java index a7fab80d29d19..174e03f842dab 100644 --- a/keystore/java/android/security/KeyStoreParameter.java +++ b/keystore/java/android/security/KeyStoreParameter.java @@ -16,145 +16,51 @@ package android.security; -import android.annotation.IntRange; import android.annotation.NonNull; -import android.annotation.Nullable; import android.app.KeyguardManager; import android.content.Context; +import android.security.keystore.KeyGenParameterSpec; +import android.security.keystore.KeyProtection; -import java.security.Key; +import java.security.KeyPairGenerator; import java.security.KeyStore.ProtectionParameter; -import java.security.cert.Certificate; -import java.util.Date; - -import javax.crypto.Cipher; /** - * Parameters specifying how to secure and restrict the use of a key or key pair being imported into - * the Android KeyStore facility. This class - * specifies whether user authentication is required for using the key, what uses the key is - * authorized for (e.g., only in {@code CTR} mode, or only for signing -- decryption not permitted), - * whether the key should be encrypted at rest, the key's and validity start and end dates. + * This provides the optional parameters that can be specified for + * {@code KeyStore} entries that work with + * Android KeyStore + * facility. The Android KeyStore facility is accessed through a + * {@link java.security.KeyStore} API using the {@code AndroidKeyStore} + * provider. The {@code context} passed in may be used to pop up some UI to ask + * the user to unlock or initialize the Android KeyStore facility. + *
+ * Any entries placed in the {@code KeyStore} may be retrieved later. Note that + * there is only one logical instance of the {@code KeyStore} per application + * UID so apps using the {@code sharedUid} facility will also share a + * {@code KeyStore}. + *
+ * Keys may be generated using the {@link KeyPairGenerator} facility with a + * {@link KeyPairGeneratorSpec} to specify the entry's {@code alias}. A + * self-signed X.509 certificate will be attached to generated entries, but that + * may be replaced at a later time by a certificate signed by a real Certificate + * Authority. * - *
To import a key or key pair into the Android KeyStore, create an instance of this class using - * the {@link Builder} and pass the instance into {@link java.security.KeyStore#setEntry(String, java.security.KeyStore.Entry, ProtectionParameter) KeyStore.setEntry} - * with the key or key pair being imported. - * - *
To obtain the secret/symmetric or private key from the Android KeyStore use - * {@link java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null)} or - * {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)}. - * To obtain the public key from the Android KeyStore use - * {@link java.security.KeyStore#getCertificate(String)} and then - * {@link Certificate#getPublicKey()}. - * - *
NOTE: The key material of keys stored in the Android KeyStore is not accessible. - * - *
{@code
- * SecretKey key = ...; // AES key
- *
- * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
- * keyStore.load(null);
- * keyStore.setEntry(
- * "key1",
- * new KeyStore.SecretKeyEntry(key),
- * new KeyStoreParameter.Builder(context)
- * .setPurposes(KeyStoreKeyProperties.PURPOSE_ENCRYPT
- * | KeyStoreKeyProperties.PURPOSE_DECRYPT)
- * .setBlockMode(KeyStoreKeyProperties.BLOCK_MODE_CBC)
- * .setEncryptionPaddings(
- * KeyStoreKeyProperties.ENCRYPTION_PADDING_PKCS7)
- * .build());
- * // Key imported, obtain a reference to it.
- * SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
- * // The original key can now be thrown away.
- * }
- *
- * {@code
- * PrivateKey privateKey = ...; // EC private key
- * Certificate[] certChain = ...; // Certificate chain with the first certificate
- * // containing the corresponding EC public key.
- *
- * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
- * keyStore.load(null);
- * keyStore.setEntry(
- * "key2",
- * new KeyStore.PrivateKeyEntry(privateKey, certChain),
- * new KeyStoreParameter.Builder(context)
- * .setPurposes(KeyStoreKeyProperties.PURPOSE_SIGN)
- * .setDigests(KeyStoreKeyProperties.DIGEST_SHA256)
- * // Only permit this key to be used if the user
- * // authenticated within the last ten minutes.
- * .setUserAuthenticationRequired(true)
- * .setUserAuthenticationValidityDurationSeconds(10 * 60)
- * .build());
- * // Key pair imported, obtain a reference to it.
- * PrivateKey keyStorePrivateKey = (PrivateKey) keyStore.getKey("key2", null);
- * PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey();
- * // The original private key can now be thrown away.
- * }
+ * @deprecated Use {@link KeyProtection} instead.
*/
+@Deprecated
public final class KeyStoreParameter implements ProtectionParameter {
private final Context mContext;
private final int mFlags;
- private final Date mKeyValidityStart;
- private final Date mKeyValidityForOriginationEnd;
- private final Date mKeyValidityForConsumptionEnd;
- private final @KeyStoreKeyProperties.PurposeEnum int mPurposes;
- private final @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
- private final @KeyStoreKeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
- private final @KeyStoreKeyProperties.DigestEnum String[] mDigests;
- private final @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes;
- private final boolean mRandomizedEncryptionRequired;
- private final boolean mUserAuthenticationRequired;
- private final int mUserAuthenticationValidityDurationSeconds;
private KeyStoreParameter(
Context context,
- int flags,
- Date keyValidityStart,
- Date keyValidityForOriginationEnd,
- Date keyValidityForConsumptionEnd,
- @KeyStoreKeyProperties.PurposeEnum int purposes,
- @KeyStoreKeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
- @KeyStoreKeyProperties.SignaturePaddingEnum String[] signaturePaddings,
- @KeyStoreKeyProperties.DigestEnum String[] digests,
- @KeyStoreKeyProperties.BlockModeEnum String[] blockModes,
- boolean randomizedEncryptionRequired,
- boolean userAuthenticationRequired,
- int userAuthenticationValidityDurationSeconds) {
+ int flags) {
if (context == null) {
throw new IllegalArgumentException("context == null");
- } else if ((userAuthenticationValidityDurationSeconds < 0)
- && (userAuthenticationValidityDurationSeconds != -1)) {
- throw new IllegalArgumentException(
- "userAuthenticationValidityDurationSeconds must not be negative");
}
mContext = context;
mFlags = flags;
- mKeyValidityStart = keyValidityStart;
- mKeyValidityForOriginationEnd = keyValidityForOriginationEnd;
- mKeyValidityForConsumptionEnd = keyValidityForConsumptionEnd;
- mPurposes = purposes;
- mEncryptionPaddings =
- ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(encryptionPaddings));
- mSignaturePaddings =
- ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(signaturePaddings));
- mDigests = ArrayUtils.cloneIfNotEmpty(digests);
- mBlockModes = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(blockModes));
- mRandomizedEncryptionRequired = randomizedEncryptionRequired;
- mUserAuthenticationRequired = userAuthenticationRequired;
- mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
}
/**
@@ -175,150 +81,19 @@ public final class KeyStoreParameter implements ProtectionParameter {
* Returns {@code true} if the {@link java.security.KeyStore} entry must be encrypted at rest.
* This will protect the entry with the secure lock screen credential (e.g., password, PIN, or
* pattern).
+ *
+ * Note that encrypting the key at rest requires that the secure lock screen (e.g., password, + * PIN, pattern) is set up, otherwise key generation will fail. Moreover, this key will be + * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device + * Administrator). Finally, this key cannot be used until the user unlocks the secure lock + * screen after boot. + * + * @see KeyguardManager#isDeviceSecure() */ public boolean isEncryptionRequired() { return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0; } - /** - * Gets the time instant before which the key is not yet valid. - * - * @return instant or {@code null} if not restricted. - */ - @Nullable - public Date getKeyValidityStart() { - return mKeyValidityStart; - } - - /** - * Gets the time instant after which the key is no long valid for decryption and verification. - * - * @return instant or {@code null} if not restricted. - */ - @Nullable - public Date getKeyValidityForConsumptionEnd() { - return mKeyValidityForConsumptionEnd; - } - - /** - * Gets the time instant after which the key is no long valid for encryption and signing. - * - * @return instant or {@code null} if not restricted. - */ - @Nullable - public Date getKeyValidityForOriginationEnd() { - return mKeyValidityForOriginationEnd; - } - - /** - * Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used. - * Attempts to use the key for any other purpose will be rejected. - * - *
See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags. - */ - public @KeyStoreKeyProperties.PurposeEnum int getPurposes() { - return mPurposes; - } - - /** - * Gets the set of padding schemes (e.g., {@code PKCS7Padding}, {@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. - * - *
See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants. - */ - @NonNull - public @KeyStoreKeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() { - return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings); - } - - /** - * Gets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key - * can be used when signing/verifying. Attempts to use the key with any other padding scheme - * will be rejected. - * - *
See {@link KeyStoreKeyProperties}.{@code SIGNATURE_PADDING} constants. - */ - @NonNull - public @KeyStoreKeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() { - return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings); - } - - /** - * 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() { - if (mDigests == null) { - throw new IllegalStateException("Digests not specified"); - } - return ArrayUtils.cloneIfNotEmpty(mDigests); - } - - /** - * Returns {@code true} if the set of digest algorithms with which the key can be used has been - * specified. - * - * @see #getDigests() - */ - @NonNull - public boolean isDigestsSpecified() { - return mDigests != null; - } - - /** - * Gets 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. - * - *
See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants. - */ - @NonNull - public @KeyStoreKeyProperties.BlockModeEnum String[] getBlockModes() { - return ArrayUtils.cloneIfNotEmpty(mBlockModes); - } - - /** - * Returns {@code true} if encryption using this key must be sufficiently randomized to produce - * different ciphertexts for the same plaintext every time. The formal cryptographic property - * being required is indistinguishability under chosen-plaintext attack ({@code - * IND-CPA}). This property is important because it mitigates several classes of - * weaknesses due to which ciphertext may leak information about plaintext. For example, if a - * given plaintext always produces the same ciphertext, an attacker may see the repeated - * ciphertexts and be able to deduce something about the plaintext. - */ - public boolean isRandomizedEncryptionRequired() { - return mRandomizedEncryptionRequired; - } - - /** - * Returns {@code true} if user authentication is required for this key to be used. - * - * @see #getUserAuthenticationValidityDurationSeconds() - */ - public boolean isUserAuthenticationRequired() { - return mUserAuthenticationRequired; - } - - /** - * Gets the duration of time (seconds) for which this key can be used after the user is - * successfully authenticated. This has effect only if user authentication is required. - * - * @return duration in seconds or {@code -1} if authentication is required for every use of the - * key. - * - * @see #isUserAuthenticationRequired() - */ - public int getUserAuthenticationValidityDurationSeconds() { - return mUserAuthenticationValidityDurationSeconds; - } - /** * Builder class for {@link KeyStoreParameter} objects. *
@@ -332,24 +107,16 @@ public final class KeyStoreParameter implements ProtectionParameter { * *
* KeyStoreParameter params = new KeyStoreParameter.Builder(mContext)
- * .setEncryptionRequired(true)
+ * .setEncryptionRequired()
* .build();
*
+ *
+ * @deprecated Use {@link KeyProtection.Builder} instead.
*/
+ @Deprecated
public final static class Builder {
private final Context mContext;
private int mFlags;
- private Date mKeyValidityStart;
- private Date mKeyValidityForOriginationEnd;
- private Date mKeyValidityForConsumptionEnd;
- private @KeyStoreKeyProperties.PurposeEnum int mPurposes;
- private @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
- private @KeyStoreKeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
- private @KeyStoreKeyProperties.DigestEnum String[] mDigests;
- private @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes;
- private boolean mRandomizedEncryptionRequired = true;
- private boolean mUserAuthenticationRequired;
- private int mUserAuthenticationValidityDurationSeconds = -1;
/**
* Creates a new instance of the {@code Builder} with the given
@@ -387,244 +154,6 @@ public final class KeyStoreParameter implements ProtectionParameter {
return this;
}
- /**
- * Sets the time instant before which the key is not yet valid.
- *
- * By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - * @see #setKeyValidityEnd(Date) - */ - @NonNull - public Builder setKeyValidityStart(Date startDate) { - mKeyValidityStart = startDate; - return this; - } - - /** - * Sets the time instant after which the key is no longer valid. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - * @see #setKeyValidityStart(Date) - * @see #setKeyValidityForConsumptionEnd(Date) - * @see #setKeyValidityForOriginationEnd(Date) - */ - @NonNull - public Builder setKeyValidityEnd(Date endDate) { - setKeyValidityForOriginationEnd(endDate); - setKeyValidityForConsumptionEnd(endDate); - return this; - } - - /** - * Sets the time instant after which the key is no longer valid for encryption and signing. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - * @see #setKeyValidityForConsumptionEnd(Date) - */ - @NonNull - public Builder setKeyValidityForOriginationEnd(Date endDate) { - mKeyValidityForOriginationEnd = endDate; - return this; - } - - /** - * Sets the time instant after which the key is no longer valid for decryption and - * verification. - * - *
By default, the key is valid at any instant. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - * @see #setKeyValidityForOriginationEnd(Date) - */ - @NonNull - public Builder setKeyValidityForConsumptionEnd(Date endDate) { - mKeyValidityForConsumptionEnd = endDate; - return this; - } - - /** - * Sets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used. - * Attempts to use the key for any other purpose will be rejected. - * - *
This must be specified for all keys. There is no default. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - *
See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags. - */ - @NonNull - public Builder setPurposes(@KeyStoreKeyProperties.PurposeEnum int purposes) { - mPurposes = purposes; - return this; - } - - /** - * Sets the set of padding schemes (e.g., {@code OAEPPadding}, {@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. - * - *
This must be specified for keys which are used for encryption/decryption. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - *
See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants. - */ - @NonNull - public Builder setEncryptionPaddings( - @KeyStoreKeyProperties.EncryptionPaddingEnum String... paddings) { - mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(paddings); - return this; - } - - /** - * Sets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key - * can be used when signing/verifying. Attempts to use the key with any other padding scheme - * will be rejected. - * - *
This must be specified for RSA keys which are used for signing/verification. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - *
See {@link KeyStoreKeyProperties}.{@code SIGNATURE_PADDING} constants. - */ - @NonNull - public Builder setSignaturePaddings( - @KeyStoreKeyProperties.SignaturePaddingEnum String... paddings) { - mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(paddings); - return this; - } - - - /** - * 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. - * - *
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. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - * @see KeyStoreKeyProperties.Digest - */ - @NonNull - public Builder setDigests(@KeyStoreKeyProperties.DigestEnum String... digests) { - mDigests = ArrayUtils.cloneIfNotEmpty(digests); - return this; - } - - /** - * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}, {@code ECB}) with which the - * key can be used when encrypting/decrypting. Attempts to use the key with any other block - * modes will be rejected. - * - *
This must be specified for encryption/decryption keys. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - *
See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants. - */ - @NonNull - public Builder setBlockModes(@KeyStoreKeyProperties.BlockModeEnum String... blockModes) { - mBlockModes = ArrayUtils.cloneIfNotEmpty(blockModes); - return this; - } - - /** - * Sets whether encryption using this key must be sufficiently randomized to produce - * different ciphertexts for the same plaintext every time. The formal cryptographic - * property being required is indistinguishability under chosen-plaintext attack - * ({@code IND-CPA}). This property is important because it mitigates several classes - * of weaknesses due to which ciphertext may leak information about plaintext. For example, - * if a given plaintext always produces the same ciphertext, an attacker may see the - * repeated ciphertexts and be able to deduce something about the plaintext. - * - *
By default, {@code IND-CPA} is required. - * - *
When {@code IND-CPA} is required: - *
Before disabling this requirement, consider the following approaches instead: - *
NOTE: This has currently no effect on asymmetric key pairs. - */ - @NonNull - public Builder setRandomizedEncryptionRequired(boolean required) { - mRandomizedEncryptionRequired = required; - return this; - } - - /** - * Sets whether user authentication is required to use this key. - * - *
By default, the key can be used without user authentication. - * - *
When user authentication is required, the user authorizes the use of the key by - * authenticating to this Android device using a subset of their secure lock screen - * credentials. Different authentication methods are used depending on whether the every - * use of the key must be authenticated (as specified by - * {@link #setUserAuthenticationValidityDurationSeconds(int)}). - * More - * information. - * - *
NOTE: This has currently no effect on asymmetric key pairs. - * - * @see #setUserAuthenticationValidityDurationSeconds(int) - */ - @NonNull - public Builder setUserAuthenticationRequired(boolean required) { - mUserAuthenticationRequired = required; - return this; - } - - /** - * Sets the duration of time (seconds) for which this key can be used after the user is - * successfully authenticated. This has effect only if user authentication is required. - * - *
By default, the user needs to authenticate for every use of the key. - * - *
NOTE: This has currently no effect on asymmetric key pairs.
- *
- * @param seconds duration in seconds or {@code -1} if the user needs to authenticate for
- * every use of the key.
- *
- * @see #setUserAuthenticationRequired(boolean)
- */
- @NonNull
- public Builder setUserAuthenticationValidityDurationSeconds(
- @IntRange(from = -1) int seconds) {
- mUserAuthenticationValidityDurationSeconds = seconds;
- return this;
- }
-
/**
* Builds the instance of the {@code KeyStoreParameter}.
*
@@ -635,18 +164,7 @@ public final class KeyStoreParameter implements ProtectionParameter {
public KeyStoreParameter build() {
return new KeyStoreParameter(
mContext,
- mFlags,
- mKeyValidityStart,
- mKeyValidityForOriginationEnd,
- mKeyValidityForConsumptionEnd,
- mPurposes,
- mEncryptionPaddings,
- mSignaturePaddings,
- mDigests,
- mBlockModes,
- mRandomizedEncryptionRequired,
- mUserAuthenticationRequired,
- mUserAuthenticationValidityDurationSeconds);
+ mFlags);
}
}
}
diff --git a/keystore/java/android/security/KeyStoreSecretKeyFactorySpi.java b/keystore/java/android/security/KeyStoreSecretKeyFactorySpi.java
index 548296b07c5d4..618ba47f3ff43 100644
--- a/keystore/java/android/security/KeyStoreSecretKeyFactorySpi.java
+++ b/keystore/java/android/security/KeyStoreSecretKeyFactorySpi.java
@@ -18,6 +18,8 @@ package android.security;
import android.security.keymaster.KeyCharacteristics;
import android.security.keymaster.KeymasterDefs;
+import android.security.keystore.KeyInfo;
+import android.security.keystore.KeyProperties;
import libcore.util.EmptyArray;
@@ -55,7 +57,7 @@ public class KeyStoreSecretKeyFactorySpi extends SecretKeyFactorySpi {
throw new InvalidKeySpecException(
"Key material export of Android KeyStore keys is not supported");
}
- if (!KeyStoreKeySpec.class.equals(keySpecClass)) {
+ if (!KeyInfo.class.equals(keySpecClass)) {
throw new InvalidKeySpecException("Unsupported key spec: " + keySpecClass.getName());
}
String keyAliasInKeystore = ((KeyStoreSecretKey) key).getAlias();
@@ -75,22 +77,22 @@ public class KeyStoreSecretKeyFactorySpi extends SecretKeyFactorySpi {
}
boolean insideSecureHardware;
- @KeyStoreKeyProperties.OriginEnum int origin;
+ @KeyProperties.OriginEnum int origin;
int keySize;
- @KeyStoreKeyProperties.PurposeEnum int purposes;
+ @KeyProperties.PurposeEnum int purposes;
String[] encryptionPaddings;
- @KeyStoreKeyProperties.DigestEnum String[] digests;
- @KeyStoreKeyProperties.BlockModeEnum String[] blockModes;
+ @KeyProperties.DigestEnum String[] digests;
+ @KeyProperties.BlockModeEnum String[] blockModes;
int keymasterSwEnforcedUserAuthenticators;
int keymasterHwEnforcedUserAuthenticators;
try {
if (keyCharacteristics.hwEnforced.containsTag(KeymasterDefs.KM_TAG_ORIGIN)) {
insideSecureHardware = true;
- origin = KeyStoreKeyProperties.Origin.fromKeymaster(
+ origin = KeyProperties.Origin.fromKeymaster(
keyCharacteristics.hwEnforced.getInt(KeymasterDefs.KM_TAG_ORIGIN, -1));
} else if (keyCharacteristics.swEnforced.containsTag(KeymasterDefs.KM_TAG_ORIGIN)) {
insideSecureHardware = false;
- origin = KeyStoreKeyProperties.Origin.fromKeymaster(
+ origin = KeyProperties.Origin.fromKeymaster(
keyCharacteristics.swEnforced.getInt(KeymasterDefs.KM_TAG_ORIGIN, -1));
} else {
throw new InvalidKeySpecException("Key origin not available");
@@ -100,15 +102,14 @@ public class KeyStoreSecretKeyFactorySpi extends SecretKeyFactorySpi {
throw new InvalidKeySpecException("Key size not available");
}
keySize = keySizeInteger;
- purposes = KeyStoreKeyProperties.Purpose.allFromKeymaster(
+ purposes = KeyProperties.Purpose.allFromKeymaster(
keyCharacteristics.getInts(KeymasterDefs.KM_TAG_PURPOSE));
List To generate an asymmetric key pair or a symmetric key, create an instance of this class using
+ * the {@link Builder}, initialize a {@code KeyPairGenerator} or a {@code KeyGenerator} of the
+ * desired key type (e.g., {@code EC} or {@code AES} -- see
+ * {@link KeyProperties}.{@code KEY_ALGORITHM} constants) from the {@code AndroidKeyStore} provider
+ * with the {@code KeyPairGeneratorSpec} instance, and then generate a key or key pair using
+ * {@link KeyPairGenerator#generateKeyPair()}.
+ *
+ * The generated key pair or key will be returned by the generator and also stored in the Android
+ * Keystore system under the alias specified in this spec. To obtain the secret or private key from
+ * the Android KeyStore use {@link java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null)}
+ * or {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)}.
+ * To obtain the public key from the Android Keystore system use
+ * {@link java.security.KeyStore#getCertificate(String)} and then
+ * {@link Certificate#getPublicKey()}.
+ *
+ * For asymmetric key pairs, a self-signed X.509 certificate will be also generated and stored in
+ * the Android KeyStore. This is because the {@link java.security.KeyStore} abstraction does not
+ * support storing key pairs without a certificate. The subject, serial number, and validity dates
+ * 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).
+ *
+ * NOTE: The key material of the generated symmetric and private keys is not accessible. The key
+ * material of the public keys is accessible.
+ *
+ * Note that encrypting the key at rest requires that the secure lock screen (e.g., password,
+ * PIN, pattern) is set up, otherwise key generation will fail. Moreover, this key will be
+ * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device
+ * Administrator). Finally, this key cannot be used until the user unlocks the secure lock
+ * screen after boot.
+ *
+ * @see KeyguardManager#isDeviceSecure()
+ */
+ public boolean isEncryptionAtRestRequired() {
+ return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0;
+ }
+
+ /**
+ * Returns the time instant before which the key is not yet valid or {@code null} if not
+ * restricted.
+ */
+ @Nullable
+ public Date getKeyValidityStart() {
+ return mKeyValidityStart;
+ }
+
+ /**
+ * Returns the time instant after which the key is no longer valid for decryption and
+ * verification or {@code null} if not restricted.
+ */
+ @Nullable
+ public Date getKeyValidityForConsumptionEnd() {
+ return mKeyValidityForConsumptionEnd;
+ }
+
+ /**
+ * Returns the time instant after which the key is no longer valid for encryption and signing
+ * or {@code null} if not restricted.
+ */
+ @Nullable
+ public Date getKeyValidityForOriginationEnd() {
+ return mKeyValidityForOriginationEnd;
+ }
+
+ /**
+ * Returns the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.
+ * Attempts to use the key for any other purpose will be rejected.
+ *
+ * See {@link KeyProperties}.{@code PURPOSE} flags.
+ */
+ public @KeyProperties.PurposeEnum int getPurposes() {
+ return mPurposes;
+ }
+
+ /**
+ * Returns the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384} with which the
+ * key can be used or {@code null} if not specified.
+ *
+ * See {@link KeyProperties}.{@code DIGEST} constants.
+ *
+ * @throws IllegalStateException if this set has not been specified.
+ *
+ * @see #isDigestsSpecified()
+ */
+ @NonNull
+ public @KeyProperties.DigestEnum String[] getDigests() {
+ if (mDigests == null) {
+ throw new IllegalStateException("Digests not specified");
+ }
+ return ArrayUtils.cloneIfNotEmpty(mDigests);
+ }
+
+ /**
+ * Returns {@code true} if the set of digest algorithms with which the key can be used has been
+ * specified.
+ *
+ * @see #getDigests()
+ */
+ @NonNull
+ public boolean isDigestsSpecified() {
+ return mDigests != null;
+ }
+
+ /**
+ * Returns the set of padding schemes (e.g., {@code PKCS7Padding}, {@code OEAPPadding},
+ * {@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.
+ *
+ * See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
+ */
+ @NonNull
+ public @KeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
+ return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings);
+ }
+
+ /**
+ * Gets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key
+ * can be used when signing/verifying. Attempts to use the key with any other padding scheme
+ * will be rejected.
+ *
+ * See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
+ */
+ @NonNull
+ public @KeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
+ return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings);
+ }
+
+ /**
+ * Gets 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.
+ *
+ * See {@link KeyProperties}.{@code BLOCK_MODE} constants.
+ */
+ @NonNull
+ public @KeyProperties.BlockModeEnum String[] getBlockModes() {
+ return ArrayUtils.cloneIfNotEmpty(mBlockModes);
+ }
+
+ /**
+ * Returns {@code true} if encryption using this key must be sufficiently randomized to produce
+ * different ciphertexts for the same plaintext every time. The formal cryptographic property
+ * being required is indistinguishability under chosen-plaintext attack ({@code
+ * IND-CPA}). This property is important because it mitigates several classes of
+ * weaknesses due to which ciphertext may leak information about plaintext. For example, if a
+ * given plaintext always produces the same ciphertext, an attacker may see the repeated
+ * ciphertexts and be able to deduce something about the plaintext.
+ */
+ public boolean isRandomizedEncryptionRequired() {
+ return mRandomizedEncryptionRequired;
+ }
+
+ /**
+ * Returns {@code true} if user authentication is required for this key to be used.
+ *
+ * This restriction applies only to private key operations. Public key operations are not
+ * restricted.
+ *
+ * @see #getUserAuthenticationValidityDurationSeconds()
+ */
+ public boolean isUserAuthenticationRequired() {
+ return mUserAuthenticationRequired;
+ }
+
+ /**
+ * Gets the duration of time (seconds) for which this key can be used after the user is
+ * successfully authenticated. This has effect only if user authentication is required.
+ *
+ * This restriction applies only to private key operations. Public key operations are not
+ * restricted.
+ *
+ * @return duration in seconds or {@code -1} if authentication is required for every use of the
+ * key.
+ *
+ * @see #isUserAuthenticationRequired()
+ */
+ public int getUserAuthenticationValidityDurationSeconds() {
+ return mUserAuthenticationValidityDurationSeconds;
+ }
+
+ /**
+ * Builder of {@link KeyGenParameterSpec} instances.
+ */
+ public final static class Builder {
+ private final String mKeystoreAlias;
+ private @KeyProperties.PurposeEnum int mPurposes;
+
+ private int mKeySize = -1;
+ private AlgorithmParameterSpec mSpec;
+ private X500Principal mCertificateSubject;
+ private BigInteger mCertificateSerialNumber;
+ private Date mCertificateNotBefore;
+ private Date mCertificateNotAfter;
+ private int mFlags;
+ private Date mKeyValidityStart;
+ private Date mKeyValidityForOriginationEnd;
+ private Date mKeyValidityForConsumptionEnd;
+ private @KeyProperties.DigestEnum String[] mDigests;
+ private @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
+ private @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
+ private @KeyProperties.BlockModeEnum String[] mBlockModes;
+ private boolean mRandomizedEncryptionRequired = true;
+ private boolean mUserAuthenticationRequired;
+ private int mUserAuthenticationValidityDurationSeconds = -1;
+
+ /**
+ * Creates a new instance of the {@code Builder}.
+ *
+ * @param keystoreAlias alias of the entry in which the generated key will appear in
+ * Android KeyStore.
+ * @param purposes set of purposes (e.g., encrypt, decrypt, sign) for which the key can be
+ * used. Attempts to use the key for any other purpose will be rejected.
+ *
+ * If the set of purposes for which the key can be used does not contain
+ * {@link KeyProperties#PURPOSE_SIGN}, the self-signed certificate generated by
+ * {@link KeyPairGenerator} of {@code AndroidKeyStore} provider will contain an
+ * invalid signature. This is OK if the certificate is only used for obtaining the
+ * public key from Android KeyStore.
+ *
+ * NOTE: The {@code purposes} parameter has currently no effect on asymmetric
+ * key pairs.
+ *
+ * See {@link KeyProperties}.{@code PURPOSE} flags.
+ */
+ public Builder(@NonNull String keystoreAlias, @KeyProperties.PurposeEnum int purposes) {
+ if (keystoreAlias == null) {
+ throw new NullPointerException("keystoreAlias == null");
+ }
+ mKeystoreAlias = keystoreAlias;
+ mPurposes = purposes;
+ }
+
+ /**
+ * Sets the size (in bits) of the key to be generated. For instance, for RSA keys this sets
+ * the modulus size, for EC keys this selects a curve with a matching field size, and for
+ * symmetric keys this sets the size of the bitstring which is their key material.
+ *
+ * The default key size is specific to each key algorithm.
+ */
+ @NonNull
+ public Builder setKeySize(int keySize) {
+ if (keySize < 0) {
+ throw new IllegalArgumentException("keySize < 0");
+ }
+ mKeySize = keySize;
+ return this;
+ }
+
+ /**
+ * Sets the algorithm-specific key generation parameters. For example, for RSA keys this may
+ * be an instance of {@link java.security.spec.RSAKeyGenParameterSpec}.
+ */
+ public Builder setAlgorithmParameterSpec(@NonNull AlgorithmParameterSpec spec) {
+ if (spec == null) {
+ throw new NullPointerException("spec == null");
+ }
+ mSpec = spec;
+ return this;
+ }
+
+ /**
+ * Sets the subject used for the self-signed certificate of the generated key pair.
+ *
+ * By default, the subject is {@code CN=fake}.
+ */
+ @NonNull
+ public Builder setCertificateSubject(@NonNull X500Principal subject) {
+ if (subject == null) {
+ throw new NullPointerException("subject == null");
+ }
+ mCertificateSubject = subject;
+ return this;
+ }
+
+ /**
+ * Sets the serial number used for the self-signed certificate of the generated key pair.
+ *
+ * By default, the serial number is {@code 1}.
+ */
+ @NonNull
+ public Builder setCertificateSerialNumber(@NonNull BigInteger serialNumber) {
+ if (serialNumber == null) {
+ throw new NullPointerException("serialNumber == null");
+ }
+ mCertificateSerialNumber = serialNumber;
+ return this;
+ }
+
+ /**
+ * Sets the start of the validity period for the self-signed certificate of the generated
+ * key pair.
+ *
+ * By default, this date is {@code Jan 1 1970}.
+ */
+ @NonNull
+ public Builder setCertificateNotBefore(@NonNull Date date) {
+ if (date == null) {
+ throw new NullPointerException("date == null");
+ }
+ mCertificateNotBefore = date;
+ return this;
+ }
+
+ /**
+ * Sets the end of the validity period for the self-signed certificate of the generated key
+ * pair.
+ *
+ * By default, this date is {@code Jan 1 2048}.
+ */
+ @NonNull
+ public Builder setCertificateNotAfter(@NonNull Date date) {
+ if (date == null) {
+ throw new NullPointerException("date == null");
+ }
+ mCertificateNotAfter = date;
+ return this;
+ }
+
+ /**
+ * Sets whether this key pair or key must be encrypted at rest. This will protect the key
+ * pair or key with the secure lock screen credential (e.g., password, PIN, or pattern).
+ *
+ * Note that enabling this feature requires that the secure lock screen (e.g., password,
+ * PIN, pattern) is set up, otherwise key generation will fail. Moreover, this key will be
+ * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device
+ * Administrator). Finally, this key cannot be used until the user unlocks the secure lock
+ * screen after boot.
+ *
+ * @see KeyguardManager#isDeviceSecure()
+ */
+ @NonNull
+ public Builder setEncryptionAtRestRequired(boolean required) {
+ if (required) {
+ mFlags |= KeyStore.FLAG_ENCRYPTED;
+ } else {
+ mFlags &= ~KeyStore.FLAG_ENCRYPTED;
+ }
+ return this;
+ }
+
+ /**
+ * Sets the time instant before which the key is not yet valid.
+ *
+ * By default, the key is valid at any instant.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * @see #setKeyValidityEnd(Date)
+ */
+ @NonNull
+ public Builder setKeyValidityStart(Date startDate) {
+ mKeyValidityStart = startDate;
+ return this;
+ }
+
+ /**
+ * Sets the time instant after which the key is no longer valid.
+ *
+ * By default, the key is valid at any instant.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * @see #setKeyValidityStart(Date)
+ * @see #setKeyValidityForConsumptionEnd(Date)
+ * @see #setKeyValidityForOriginationEnd(Date)
+ */
+ @NonNull
+ public Builder setKeyValidityEnd(Date endDate) {
+ setKeyValidityForOriginationEnd(endDate);
+ setKeyValidityForConsumptionEnd(endDate);
+ return this;
+ }
+
+ /**
+ * Sets the time instant after which the key is no longer valid for encryption and signing.
+ *
+ * By default, the key is valid at any instant.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * @see #setKeyValidityForConsumptionEnd(Date)
+ */
+ @NonNull
+ public Builder setKeyValidityForOriginationEnd(Date endDate) {
+ mKeyValidityForOriginationEnd = endDate;
+ return this;
+ }
+
+ /**
+ * Sets the time instant after which the key is no longer valid for decryption and
+ * verification.
+ *
+ * By default, the key is valid at any instant.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * @see #setKeyValidityForOriginationEnd(Date)
+ */
+ @NonNull
+ public Builder setKeyValidityForConsumptionEnd(Date endDate) {
+ mKeyValidityForConsumptionEnd = endDate;
+ return this;
+ }
+
+ /**
+ * 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.
+ *
+ * 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}
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * @see KeyProperties.Digest
+ */
+ @NonNull
+ public Builder setDigests(@KeyProperties.DigestEnum String... digests) {
+ mDigests = ArrayUtils.cloneIfNotEmpty(digests);
+ return this;
+ }
+
+ /**
+ * Sets the set of padding schemes (e.g., {@code PKCS7Padding}, {@code OAEPPadding},
+ * {@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.
+ *
+ * This must be specified for keys which are used for encryption/decryption.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
+ */
+ @NonNull
+ public Builder setEncryptionPaddings(
+ @KeyProperties.EncryptionPaddingEnum String... paddings) {
+ mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(paddings);
+ return this;
+ }
+
+ /**
+ * Sets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key
+ * can be used when signing/verifying. Attempts to use the key with any other padding scheme
+ * will be rejected.
+ *
+ * This must be specified for RSA keys which are used for signing/verification.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
+ */
+ @NonNull
+ public Builder setSignaturePaddings(
+ @KeyProperties.SignaturePaddingEnum String... paddings) {
+ mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(paddings);
+ return this;
+ }
+
+ /**
+ * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}, {@code ECB}) with which the
+ * key can be used when encrypting/decrypting. Attempts to use the key with any other block
+ * modes will be rejected.
+ *
+ * This must be specified for encryption/decryption keys.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code BLOCK_MODE} constants.
+ */
+ @NonNull
+ public Builder setBlockModes(@KeyProperties.BlockModeEnum String... blockModes) {
+ mBlockModes = ArrayUtils.cloneIfNotEmpty(blockModes);
+ return this;
+ }
+
+ /**
+ * Sets whether encryption using this key must be sufficiently randomized to produce
+ * different ciphertexts for the same plaintext every time. The formal cryptographic
+ * property being required is indistinguishability under chosen-plaintext attack
+ * ({@code IND-CPA}). This property is important because it mitigates several classes
+ * of weaknesses due to which ciphertext may leak information about plaintext. For example,
+ * if a given plaintext always produces the same ciphertext, an attacker may see the
+ * repeated ciphertexts and be able to deduce something about the plaintext.
+ *
+ * By default, {@code IND-CPA} is required.
+ *
+ * When {@code IND-CPA} is required:
+ * Before disabling this requirement, consider the following approaches instead:
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ */
+ @NonNull
+ public Builder setRandomizedEncryptionRequired(boolean required) {
+ mRandomizedEncryptionRequired = required;
+ return this;
+ }
+
+ /**
+ * Sets whether user authentication is required to use this key.
+ *
+ * By default, the key can be used without user authentication.
+ *
+ * When user authentication is required, the user authorizes the use of the key by
+ * authenticating to this Android device using a subset of their secure lock screen
+ * credentials. Different authentication methods are used depending on whether the every
+ * use of the key must be authenticated (as specified by
+ * {@link #setUserAuthenticationValidityDurationSeconds(int)}).
+ * More
+ * information.
+ *
+ * This restriction applies only to private key operations. Public key operations are not
+ * restricted.
+ *
+ * NOTE: This has currently no effect.
+ *
+ * @see #setUserAuthenticationValidityDurationSeconds(int)
+ */
+ @NonNull
+ public Builder setUserAuthenticationRequired(boolean required) {
+ mUserAuthenticationRequired = required;
+ return this;
+ }
+
+ /**
+ * Sets the duration of time (seconds) for which this key can be used after the user is
+ * successfully authenticated. This has effect only if user authentication is required.
+ *
+ * By default, the user needs to authenticate for every use of the key.
+ *
+ * NOTE: This has currently no effect.
+ *
+ * @param seconds duration in seconds or {@code -1} if the user needs to authenticate for
+ * every use of the key.
+ *
+ * @see #setUserAuthenticationRequired(boolean)
+ */
+ @NonNull
+ public Builder setUserAuthenticationValidityDurationSeconds(
+ @IntRange(from = -1) int seconds) {
+ mUserAuthenticationValidityDurationSeconds = seconds;
+ return this;
+ }
+
+ /**
+ * Builds an instance of {@code KeyGenParameterSpec}.
+ *
+ * @throws IllegalArgumentException if a required field is missing
+ */
+ @NonNull
+ public KeyGenParameterSpec build() {
+ return new KeyGenParameterSpec(
+ mKeystoreAlias,
+ mKeySize,
+ mSpec,
+ mCertificateSubject,
+ mCertificateSerialNumber,
+ mCertificateNotBefore,
+ mCertificateNotAfter,
+ mFlags,
+ mKeyValidityStart,
+ mKeyValidityForOriginationEnd,
+ mKeyValidityForConsumptionEnd,
+ mPurposes,
+ mDigests,
+ mEncryptionPaddings,
+ mSignaturePaddings,
+ mBlockModes,
+ mRandomizedEncryptionRequired,
+ mUserAuthenticationRequired,
+ mUserAuthenticationValidityDurationSeconds);
+ }
+ }
+}
diff --git a/keystore/java/android/security/KeyStoreKeySpec.java b/keystore/java/android/security/keystore/KeyInfo.java
similarity index 76%
rename from keystore/java/android/security/KeyStoreKeySpec.java
rename to keystore/java/android/security/keystore/KeyInfo.java
index 4c43f892207b4..aec2512a01852 100644
--- a/keystore/java/android/security/KeyStoreKeySpec.java
+++ b/keystore/java/android/security/keystore/KeyInfo.java
@@ -14,10 +14,11 @@
* limitations under the License.
*/
-package android.security;
+package android.security.keystore;
import android.annotation.NonNull;
import android.annotation.Nullable;
+import android.security.ArrayUtils;
import java.security.PrivateKey;
import java.security.spec.KeySpec;
@@ -27,55 +28,55 @@ import javax.crypto.SecretKey;
/**
* Information about a key from the Android
- * KeyStore. This class describes whether the key material is available in
+ * Keystore system. This class describes whether the key material is available in
* plaintext outside of secure hardware, whether user authentication is required for using the key
* and whether this requirement is enforced by secure hardware, the key's origin, what uses the key
* is authorized for (e.g., only in {@code CBC} mode, or signing only), whether the key should be
* encrypted at rest, the key's and validity start and end dates.
*
* See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags.
+ * See {@link KeyProperties}.{@code PURPOSE} flags.
*/
- public @KeyStoreKeyProperties.PurposeEnum int getPurposes() {
+ public @KeyProperties.PurposeEnum int getPurposes() {
return mPurposes;
}
@@ -193,10 +194,10 @@ public class KeyStoreKeySpec implements KeySpec {
* when encrypting/decrypting. Attempts to use the key with any other block modes will be
* rejected.
*
- * See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants.
+ * See {@link KeyProperties}.{@code BLOCK_MODE} constants.
*/
@NonNull
- public @KeyStoreKeyProperties.BlockModeEnum String[] getBlockModes() {
+ public @KeyProperties.BlockModeEnum String[] getBlockModes() {
return ArrayUtils.cloneIfNotEmpty(mBlockModes);
}
@@ -205,10 +206,10 @@ public class KeyStoreKeySpec implements KeySpec {
* {@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.
*
- * See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants.
+ * See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
*/
@NonNull
- public @KeyStoreKeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
+ public @KeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings);
}
@@ -217,10 +218,10 @@ public class KeyStoreKeySpec implements KeySpec {
* can be used when signing/verifying. Attempts to use the key with any other padding scheme
* will be rejected.
*
- * See {@link KeyStoreKeyProperties}.{@code SIGNATURE_PADDING} constants.
+ * See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
*/
@NonNull
- public @KeyStoreKeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
+ public @KeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings);
}
@@ -228,10 +229,10 @@ public class KeyStoreKeySpec implements KeySpec {
* Gets the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which the key
* can be used.
*
- * @see KeyStoreKeyProperties.Digest
+ * See {@link KeyProperties}.{@code DIGEST} constants.
*/
@NonNull
- public @KeyStoreKeyProperties.DigestEnum String[] getDigests() {
+ public @KeyProperties.DigestEnum String[] getDigests() {
return ArrayUtils.cloneIfNotEmpty(mDigests);
}
diff --git a/keystore/java/android/security/KeyNotYetValidException.java b/keystore/java/android/security/keystore/KeyNotYetValidException.java
similarity index 97%
rename from keystore/java/android/security/KeyNotYetValidException.java
rename to keystore/java/android/security/keystore/KeyNotYetValidException.java
index 4ea27efc79098..2cec77de5c5a8 100644
--- a/keystore/java/android/security/KeyNotYetValidException.java
+++ b/keystore/java/android/security/keystore/KeyNotYetValidException.java
@@ -14,7 +14,7 @@
* limitations under the License.
*/
-package android.security;
+package android.security.keystore;
import java.security.InvalidKeyException;
diff --git a/keystore/java/android/security/KeyPermanentlyInvalidatedException.java b/keystore/java/android/security/keystore/KeyPermanentlyInvalidatedException.java
similarity index 98%
rename from keystore/java/android/security/KeyPermanentlyInvalidatedException.java
rename to keystore/java/android/security/keystore/KeyPermanentlyInvalidatedException.java
index 229eab0b8d6a2..e320c9cbc290e 100644
--- a/keystore/java/android/security/KeyPermanentlyInvalidatedException.java
+++ b/keystore/java/android/security/keystore/KeyPermanentlyInvalidatedException.java
@@ -14,7 +14,7 @@
* limitations under the License.
*/
-package android.security;
+package android.security.keystore;
import java.security.InvalidKeyException;
diff --git a/keystore/java/android/security/KeyStoreKeyProperties.java b/keystore/java/android/security/keystore/KeyProperties.java
similarity index 90%
rename from keystore/java/android/security/KeyStoreKeyProperties.java
rename to keystore/java/android/security/keystore/KeyProperties.java
index b58a7ddae9a87..e3c2d1deaa3d6 100644
--- a/keystore/java/android/security/KeyStoreKeyProperties.java
+++ b/keystore/java/android/security/keystore/KeyProperties.java
@@ -14,7 +14,7 @@
* limitations under the License.
*/
-package android.security;
+package android.security.keystore;
import android.annotation.IntDef;
import android.annotation.NonNull;
@@ -30,10 +30,10 @@ import java.util.Collection;
import java.util.Locale;
/**
- * Properties of {@code AndroidKeyStore} keys.
+ * Properties of Android Keystore keys.
*/
-public abstract class KeyStoreKeyProperties {
- private KeyStoreKeyProperties() {}
+public abstract class KeyProperties {
+ private KeyProperties() {}
/**
* @hide
@@ -68,10 +68,13 @@ public abstract class KeyStoreKeyProperties {
*/
public static final int PURPOSE_VERIFY = 1 << 3;
- static abstract class Purpose {
+ /**
+ * @hide
+ */
+ public static abstract class Purpose {
private Purpose() {}
- static int toKeymaster(@PurposeEnum int purpose) {
+ public static int toKeymaster(@PurposeEnum int purpose) {
switch (purpose) {
case PURPOSE_ENCRYPT:
return KeymasterDefs.KM_PURPOSE_ENCRYPT;
@@ -86,7 +89,7 @@ public abstract class KeyStoreKeyProperties {
}
}
- static @PurposeEnum int fromKeymaster(int purpose) {
+ public static @PurposeEnum int fromKeymaster(int purpose) {
switch (purpose) {
case KeymasterDefs.KM_PURPOSE_ENCRYPT:
return PURPOSE_ENCRYPT;
@@ -102,7 +105,7 @@ public abstract class KeyStoreKeyProperties {
}
@NonNull
- static int[] allToKeymaster(@PurposeEnum int purposes) {
+ public static int[] allToKeymaster(@PurposeEnum int purposes) {
int[] result = getSetFlags(purposes);
for (int i = 0; i < result.length; i++) {
result[i] = toKeymaster(result[i]);
@@ -110,7 +113,7 @@ public abstract class KeyStoreKeyProperties {
return result;
}
- static @PurposeEnum int allFromKeymaster(@NonNull Collection To generate a key, create an instance of this class using the {@link Builder}, initialize a
- * {@code KeyGenerator} of the desired key type (e.g., {@code AES} or {@code HmacSHA256}) from the
- * {@code AndroidKeyStore} provider with the {@code KeyGeneratorSpec} instance, and then generate a
- * key using {@link KeyGenerator#generateKey()}.
+ * To import a key or key pair into the Android KeyStore, create an instance of this class using
+ * the {@link Builder} and pass the instance into {@link java.security.KeyStore#setEntry(String, java.security.KeyStore.Entry, ProtectionParameter) KeyStore.setEntry}
+ * with the key or key pair being imported.
*
- * The generated key will be returned by the {@code KeyGenerator} and also stored in the Android
- * KeyStore under the alias specified in this {@code KeyGeneratorSpec}. To obtain the key from the
- * Android KeyStore use
+ * To obtain the secret/symmetric or private key from the Android KeyStore use
* {@link java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null)} or
* {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)}.
+ * To obtain the public key from the Android KeyStore use
+ * {@link java.security.KeyStore#getCertificate(String)} and then
+ * {@link Certificate#getPublicKey()}.
*
- * NOTE: The key material of the keys generating using the {@code KeyGeneratorSpec} is not
- * accessible.
+ * NOTE: The key material of keys stored in the Android KeyStore is not accessible.
*
- * See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags.
+ * See {@link KeyProperties}.{@code PURPOSE} flags.
*/
- public @KeyStoreKeyProperties.PurposeEnum int getPurposes() {
+ public @KeyProperties.PurposeEnum int getPurposes() {
return mPurposes;
}
/**
- * Gets 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.
+ * Gets the set of padding schemes (e.g., {@code PKCS7Padding}, {@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.
*
- * See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants.
+ * See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
*/
@NonNull
- public @KeyStoreKeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
+ public @KeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings);
}
+ /**
+ * Gets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key
+ * can be used when signing/verifying. Attempts to use the key with any other padding scheme
+ * will be rejected.
+ *
+ * See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
+ */
+ @NonNull
+ public @KeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
+ return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings);
+ }
+
+ /**
+ * Gets the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which the key
+ * can be used.
+ *
+ * See {@link KeyProperties}.{@code DIGEST} constants.
+ *
+ * @throws IllegalStateException if this set has not been specified.
+ *
+ * @see #isDigestsSpecified()
+ */
+ @NonNull
+ public @KeyProperties.DigestEnum String[] getDigests() {
+ if (mDigests == null) {
+ throw new IllegalStateException("Digests not specified");
+ }
+ return ArrayUtils.cloneIfNotEmpty(mDigests);
+ }
+
+ /**
+ * Returns {@code true} if the set of digest algorithms with which the key can be used has been
+ * specified.
+ *
+ * @see #getDigests()
+ */
+ public boolean isDigestsSpecified() {
+ return mDigests != null;
+ }
+
/**
* Gets 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.
*
- * See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants.
+ * See {@link KeyProperties}.{@code BLOCK_MODE} constants.
*/
@NonNull
- public @KeyStoreKeyProperties.BlockModeEnum String[] getBlockModes() {
+ public @KeyProperties.BlockModeEnum String[] getBlockModes() {
return ArrayUtils.cloneIfNotEmpty(mBlockModes);
}
@@ -261,82 +307,58 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
}
/**
- * Returns {@code true} if the key must be encrypted at rest. This will protect the key with the
- * secure lock screen credential (e.g., password, PIN, or pattern).
+ * Builder of {@link KeyProtection} instances.
*/
- public boolean isEncryptionRequired() {
- return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0;
- }
+ public final static class Builder {
+ private @KeyProperties.PurposeEnum int mPurposes;
- public static class Builder {
- private final Context mContext;
- private String mKeystoreAlias;
private int mFlags;
- private int mKeySize = -1;
private Date mKeyValidityStart;
private Date mKeyValidityForOriginationEnd;
private Date mKeyValidityForConsumptionEnd;
- private @KeyStoreKeyProperties.PurposeEnum int mPurposes;
- private @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
- private @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes;
+ private @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
+ private @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
+ private @KeyProperties.DigestEnum String[] mDigests;
+ private @KeyProperties.BlockModeEnum String[] mBlockModes;
private boolean mRandomizedEncryptionRequired = true;
private boolean mUserAuthenticationRequired;
private int mUserAuthenticationValidityDurationSeconds = -1;
/**
- * Creates a new instance of the {@code Builder} with the given {@code context}. The
- * {@code context} passed in may be used to pop up some UI to ask the user to unlock or
- * initialize the Android KeyStore facility.
+ * Creates a new instance of the {@code Builder}.
+ *
+ * @param purposes set of purposes (e.g., encrypt, decrypt, sign) for which the key can be
+ * used. Attempts to use the key for any other purpose will be rejected.
+ *
+ * NOTE: The {@code purposes} parameter has currently no effect on asymmetric
+ * key pairs.
+ *
+ * See {@link KeyProperties}.{@code PURPOSE} flags.
*/
- public Builder(@NonNull Context context) {
- if (context == null) {
- throw new NullPointerException("context == null");
- }
- mContext = context;
+ public Builder(@KeyProperties.PurposeEnum int purposes) {
+ mPurposes = purposes;
}
/**
- * Sets the alias to be used to retrieve the key later from a {@link java.security.KeyStore}
- * instance using the {@code AndroidKeyStore} provider.
+ * Sets whether this {@link java.security.KeyStore} entry must be encrypted at rest.
+ * Encryption at rest will protect the entry with the secure lock screen credential (e.g.,
+ * password, PIN, or pattern).
*
- * The alias must be provided. There is no default.
- */
- @NonNull
- public Builder setAlias(@NonNull String alias) {
- if (alias == null) {
- throw new NullPointerException("alias == null");
- }
- mKeystoreAlias = alias;
- return this;
- }
-
- /**
- * Sets the size (in bits) of the key to be generated.
- *
- * By default, the key size will be determines based on the key algorithm. For example,
- * for {@code HmacSHA256}, the key size will default to {@code 256}.
- */
- @NonNull
- public Builder setKeySize(int keySize) {
- mKeySize = keySize;
- return this;
- }
-
- /**
- * Indicates that this key must be encrypted at rest. This will protect the key with the
- * secure lock screen credential (e.g., password, PIN, or pattern).
- *
- * Note that this feature requires that the secure lock screen (e.g., password, PIN,
- * pattern) is set up, otherwise key generation will fail. Moreover, this key will be
- * deleted when the secure lock screen is disabled or reset (e.g., by the user or a Device
- * Administrator). Finally, this key cannot be used until the user unlocks the secure lock
- * screen after boot.
+ * Note that enabling this feature requires that the secure lock screen (e.g., password,
+ * PIN, pattern) is set up, otherwise setting the {@code KeyStore} entry will fail.
+ * Moreover, this entry will be deleted when the secure lock screen is disabled or reset
+ * (e.g., by the user or a Device Administrator). Finally, this entry cannot be used until
+ * the user unlocks the secure lock screen after boot.
*
* @see KeyguardManager#isDeviceSecure()
*/
@NonNull
- public Builder setEncryptionRequired() {
- mFlags |= KeyStore.FLAG_ENCRYPTED;
+ public Builder setEncryptionAtRestRequired(boolean required) {
+ if (required) {
+ mFlags |= KeyStore.FLAG_ENCRYPTED;
+ } else {
+ mFlags &= ~KeyStore.FLAG_ENCRYPTED;
+ }
return this;
}
@@ -345,6 +367,8 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
*
* By default, the key is valid at any instant.
*
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
* @see #setKeyValidityEnd(Date)
*/
@NonNull
@@ -358,6 +382,8 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
*
* By default, the key is valid at any instant.
*
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
* @see #setKeyValidityStart(Date)
* @see #setKeyValidityForConsumptionEnd(Date)
* @see #setKeyValidityForOriginationEnd(Date)
@@ -374,6 +400,8 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
*
* By default, the key is valid at any instant.
*
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
* @see #setKeyValidityForConsumptionEnd(Date)
*/
@NonNull
@@ -388,6 +416,8 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
*
* By default, the key is valid at any instant.
*
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
* @see #setKeyValidityForOriginationEnd(Date)
*/
@NonNull
@@ -397,46 +427,73 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
}
/**
- * Sets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.
- * Attempts to use the key for any other purpose will be rejected.
- *
- * This must be specified for all keys. There is no default.
- *
- * See {@link KeyStoreKeyProperties}.{@code PURPOSE} flags.
- */
- @NonNull
- public Builder setPurposes(@KeyStoreKeyProperties.PurposeEnum int purposes) {
- mPurposes = purposes;
- return this;
- }
-
- /**
- * 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.
+ * Sets the set of padding schemes (e.g., {@code OAEPPadding}, {@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.
*
* This must be specified for keys which are used for encryption/decryption.
*
- * See {@link KeyStoreKeyProperties}.{@code ENCRYPTION_PADDING} constants.
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
*/
@NonNull
public Builder setEncryptionPaddings(
- @KeyStoreKeyProperties.EncryptionPaddingEnum String... paddings) {
+ @KeyProperties.EncryptionPaddingEnum String... paddings) {
mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(paddings);
return this;
}
/**
- * 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.
+ * Sets the set of padding schemes (e.g., {@code PSS}, {@code PKCS#1}) with which the key
+ * can be used when signing/verifying. Attempts to use the key with any other padding scheme
+ * will be rejected.
+ *
+ * This must be specified for RSA keys which are used for signing/verification.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
+ */
+ @NonNull
+ public Builder setSignaturePaddings(
+ @KeyProperties.SignaturePaddingEnum String... paddings) {
+ mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(paddings);
+ return this;
+ }
+
+ /**
+ * 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.
+ *
+ * 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.
+ *
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code DIGEST} constants.
+ */
+ @NonNull
+ public Builder setDigests(@KeyProperties.DigestEnum String... digests) {
+ mDigests = ArrayUtils.cloneIfNotEmpty(digests);
+ return this;
+ }
+
+ /**
+ * Sets the set of block modes (e.g., {@code CBC}, {@code CTR}, {@code ECB}) with which the
+ * key can be used when encrypting/decrypting. Attempts to use the key with any other block
+ * modes will be rejected.
*
* This must be specified for encryption/decryption keys.
*
- * See {@link KeyStoreKeyProperties}.{@code BLOCK_MODE} constants.
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
+ * See {@link KeyProperties}.{@code BLOCK_MODE} constants.
*/
@NonNull
- public Builder setBlockModes(@KeyStoreKeyProperties.BlockModeEnum String... blockModes) {
+ public Builder setBlockModes(@KeyProperties.BlockModeEnum String... blockModes) {
mBlockModes = ArrayUtils.cloneIfNotEmpty(blockModes);
return this;
}
@@ -454,11 +511,11 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
*
* When {@code IND-CPA} is required:
* Before disabling this requirement, consider the following approaches instead:
* NOTE: This has currently no effect on asymmetric key pairs.
*/
@NonNull
public Builder setRandomizedEncryptionRequired(boolean required) {
@@ -492,6 +553,8 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
* More
* information.
*
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
* @see #setUserAuthenticationValidityDurationSeconds(int)
*/
@NonNull
@@ -506,6 +569,8 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
*
* By default, the user needs to authenticate for every use of the key.
*
+ * NOTE: This has currently no effect on asymmetric key pairs.
+ *
* @param seconds duration in seconds or {@code -1} if the user needs to authenticate for
* every use of the key.
*
@@ -519,21 +584,21 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
}
/**
- * Builds a new instance instance of {@code KeyGeneratorSpec}.
+ * Builds an instance of {@link KeyProtection}.
*
- * @throws IllegalArgumentException if a required field is missing or violates a constraint.
+ * @throws IllegalArgumentException if a required field is missing
*/
@NonNull
- public KeyGeneratorSpec build() {
- return new KeyGeneratorSpec(mContext,
- mKeystoreAlias,
+ public KeyProtection build() {
+ return new KeyProtection(
mFlags,
- mKeySize,
mKeyValidityStart,
mKeyValidityForOriginationEnd,
mKeyValidityForConsumptionEnd,
mPurposes,
mEncryptionPaddings,
+ mSignaturePaddings,
+ mDigests,
mBlockModes,
mRandomizedEncryptionRequired,
mUserAuthenticationRequired,
diff --git a/keystore/java/android/security/UserNotAuthenticatedException.java b/keystore/java/android/security/keystore/UserNotAuthenticatedException.java
similarity index 97%
rename from keystore/java/android/security/UserNotAuthenticatedException.java
rename to keystore/java/android/security/keystore/UserNotAuthenticatedException.java
index 2954fa7c0bb27..21f861c0524b7 100644
--- a/keystore/java/android/security/UserNotAuthenticatedException.java
+++ b/keystore/java/android/security/keystore/UserNotAuthenticatedException.java
@@ -14,7 +14,7 @@
* limitations under the License.
*/
-package android.security;
+package android.security.keystore;
import java.security.InvalidKeyException;
diff --git a/keystore/tests/src/android/security/KeyPairGeneratorSpecTest.java b/keystore/tests/src/android/security/KeyPairGeneratorSpecTest.java
index 681a9ff9a039a..bc8dd13e99f3e 100644
--- a/keystore/tests/src/android/security/KeyPairGeneratorSpecTest.java
+++ b/keystore/tests/src/android/security/KeyPairGeneratorSpecTest.java
@@ -24,11 +24,6 @@ import java.util.Date;
import javax.security.auth.x500.X500Principal;
public class KeyPairGeneratorSpecTest extends AndroidTestCase {
- private static final X500Principal DEFAULT_CERT_SUBJECT = new X500Principal("CN=fake");
- private static final BigInteger DEFAULT_CERT_SERIAL_NUMBER = new BigInteger("1");
- private static final Date DEFAULT_CERT_NOT_BEFORE = new Date(0L); // Jan 1 1980
- private static final Date DEFAULT_CERT_NOT_AFTER = new Date(2461449600000L); // Jan 1 2048
-
private static final String TEST_ALIAS_1 = "test1";
private static final X500Principal TEST_DN_1 = new X500Principal("CN=test1");
@@ -110,37 +105,46 @@ public class KeyPairGeneratorSpecTest extends AndroidTestCase {
}
}
- public void testConstructor_NullSubjectDN_Success() throws Exception {
- KeyPairGeneratorSpec spec = new KeyPairGeneratorSpec(
- getContext(), TEST_ALIAS_1, "RSA", 1024, null, null, SERIAL_1, NOW,
- NOW_PLUS_10_YEARS, 0);
- assertEquals(DEFAULT_CERT_SUBJECT, spec.getSubjectDN());
+ public void testConstructor_NullSubjectDN_Failure() throws Exception {
+ try {
+ new KeyPairGeneratorSpec(getContext(), TEST_ALIAS_1, "RSA", 1024, null, null, SERIAL_1, NOW,
+ NOW_PLUS_10_YEARS, 0);
+ fail("Should throw IllegalArgumentException when subjectDN is null");
+ } catch (IllegalArgumentException success) {
+ }
}
- public void testConstructor_NullSerial_Success() throws Exception {
- KeyPairGeneratorSpec spec = new KeyPairGeneratorSpec(
- getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, null, NOW,
- NOW_PLUS_10_YEARS, 0);
- assertEquals(DEFAULT_CERT_SERIAL_NUMBER, spec.getSerialNumber());
+ public void testConstructor_NullSerial_Failure() throws Exception {
+ try {
+ new KeyPairGeneratorSpec(getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, null, NOW,
+ NOW_PLUS_10_YEARS, 0);
+ fail("Should throw IllegalArgumentException when startDate is null");
+ } catch (IllegalArgumentException success) {
+ }
}
- public void testConstructor_NullStartDate_Success() throws Exception {
- KeyPairGeneratorSpec spec = new KeyPairGeneratorSpec(
- getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, SERIAL_1, null,
- NOW_PLUS_10_YEARS, 0);
- assertEquals(DEFAULT_CERT_NOT_BEFORE, spec.getStartDate());
+ public void testConstructor_NullStartDate_Failure() throws Exception {
+ try {
+ new KeyPairGeneratorSpec(getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, SERIAL_1,
+ null, NOW_PLUS_10_YEARS, 0);
+ fail("Should throw IllegalArgumentException when startDate is null");
+ } catch (IllegalArgumentException success) {
+ }
}
- public void testConstructor_NullEndDate_Success() throws Exception {
- KeyPairGeneratorSpec spec = new KeyPairGeneratorSpec(
- getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, SERIAL_1, NOW, null, 0);
- assertEquals(DEFAULT_CERT_NOT_AFTER, spec.getEndDate());
+ public void testConstructor_NullEndDate_Failure() throws Exception {
+ try {
+ new KeyPairGeneratorSpec(getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, SERIAL_1,
+ NOW, null, 0);
+ fail("Should throw IllegalArgumentException when keystoreAlias is null");
+ } catch (IllegalArgumentException success) {
+ }
}
public void testConstructor_EndBeforeStart_Failure() throws Exception {
try {
- new KeyPairGeneratorSpec(getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1,
- SERIAL_1, NOW_PLUS_10_YEARS, NOW, 0);
+ new KeyPairGeneratorSpec(getContext(), TEST_ALIAS_1, "RSA", 1024, null, TEST_DN_1, SERIAL_1,
+ NOW_PLUS_10_YEARS, NOW, 0);
fail("Should throw IllegalArgumentException when end is before start");
} catch (IllegalArgumentException success) {
}
diff --git a/keystore/tests/src/android/security/KeyStoreTest.java b/keystore/tests/src/android/security/KeyStoreTest.java
index d138c248e08d5..7421120407d97 100644
--- a/keystore/tests/src/android/security/KeyStoreTest.java
+++ b/keystore/tests/src/android/security/KeyStoreTest.java
@@ -21,7 +21,6 @@ import android.os.Binder;
import android.os.IBinder;
import android.os.Process;
import android.os.ServiceManager;
-import android.security.KeyStore;
import android.security.keymaster.ExportResult;
import android.security.keymaster.KeyCharacteristics;
import android.security.keymaster.KeymasterArguments;
Example: Asymmetric key pair
+ * The following example illustrates how to generate an EC key pair in the Android KeyStore system
+ * under alias {@code key1} authorized to be used only for signing using SHA-256, SHA-384,
+ * or SHA-512 digest and only if the user has been authenticated within the last five minutes.
+ * {@code
+ * KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
+ * KeyProperties.KEY_ALGORITHM_EC,
+ * "AndroidKeyStore");
+ * keyPairGenerator.initialize(
+ * new KeyGenParameterSpec.Builder("key1",
+ * KeyProperties.PURPOSE_SIGN | KeyProperties.PURPOSE_VERIFY)
+ * .setDigests(KeyProperties.DIGEST_SHA256
+ * | KeyProperties.DIGEST_SHA384
+ * | KeyProperties.DIGEST_SHA512)
+ * // Only permit this key to be used if the user authenticated
+ * // within the last five minutes.
+ * .setUserAuthenticationRequired(true)
+ * .setUserAuthenticationValidityDurationSeconds(5 * 60)
+ * .build());
+ * KeyPair keyPair = keyPairGenerator.generateKeyPair();
+ *
+ * // The key pair can also be obtained from the Android Keystore any time as follows:
+ * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
+ * keyStore.load(null);
+ * PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
+ * PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
+ * }
+ *
+ * Example: Symmetric key
+ * The following example illustrates how to generate an AES key in the Android KeyStore system under
+ * alias {@code key2} authorized to be used only for encryption/decryption in CTR mode.
+ * {@code
+ * KeyGenerator keyGenerator = KeyGenerator.getInstance(
+ * KeyProperties.KEY_ALGORITHM_HMAC_SHA256,
+ * "AndroidKeyStore");
+ * keyGenerator.initialize(
+ * new KeyGenParameterSpec.Builder("key2",
+ * KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
+ * .setBlockModes(KeyProperties.BLOCK_MODE_CTR)
+ * .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
+ * .build());
+ * SecretKey key = keyGenerator.generateKey();
+ *
+ * // The key can also be obtained from the Android Keystore any time as follows:
+ * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
+ * keyStore.load(null);
+ * key = (SecretKey) keyStore.getKey("key2", null);
+ * }
+ */
+public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
+
+ private static final X500Principal DEFAULT_CERT_SUBJECT = new X500Principal("CN=fake");
+ private static final BigInteger DEFAULT_CERT_SERIAL_NUMBER = new BigInteger("1");
+ private static final Date DEFAULT_CERT_NOT_BEFORE = new Date(0L); // Jan 1 1970
+ private static final Date DEFAULT_CERT_NOT_AFTER = new Date(2461449600000L); // Jan 1 2048
+
+ private final String mKeystoreAlias;
+ private final int mKeySize;
+ private final AlgorithmParameterSpec mSpec;
+ private final X500Principal mCertificateSubject;
+ private final BigInteger mCertificateSerialNumber;
+ private final Date mCertificateNotBefore;
+ private final Date mCertificateNotAfter;
+ private final int mFlags;
+ private final Date mKeyValidityStart;
+ private final Date mKeyValidityForOriginationEnd;
+ private final Date mKeyValidityForConsumptionEnd;
+ private final @KeyProperties.PurposeEnum int mPurposes;
+ private final @KeyProperties.DigestEnum String[] mDigests;
+ private final @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
+ private final @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
+ private final @KeyProperties.BlockModeEnum String[] mBlockModes;
+ private final boolean mRandomizedEncryptionRequired;
+ private final boolean mUserAuthenticationRequired;
+ private final int mUserAuthenticationValidityDurationSeconds;
+
+ /**
+ * @hide should be built with Builder
+ */
+ public KeyGenParameterSpec(
+ String keyStoreAlias,
+ int keySize,
+ AlgorithmParameterSpec spec,
+ X500Principal certificateSubject,
+ BigInteger certificateSerialNumber,
+ Date certificateNotBefore,
+ Date certificateNotAfter,
+ int flags,
+ Date keyValidityStart,
+ Date keyValidityForOriginationEnd,
+ Date keyValidityForConsumptionEnd,
+ @KeyProperties.PurposeEnum int purposes,
+ @KeyProperties.DigestEnum String[] digests,
+ @KeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
+ @KeyProperties.SignaturePaddingEnum String[] signaturePaddings,
+ @KeyProperties.BlockModeEnum String[] blockModes,
+ boolean randomizedEncryptionRequired,
+ boolean userAuthenticationRequired,
+ int userAuthenticationValidityDurationSeconds) {
+ if (TextUtils.isEmpty(keyStoreAlias)) {
+ throw new IllegalArgumentException("keyStoreAlias must not be empty");
+ } else if ((userAuthenticationValidityDurationSeconds < 0)
+ && (userAuthenticationValidityDurationSeconds != -1)) {
+ throw new IllegalArgumentException(
+ "userAuthenticationValidityDurationSeconds must not be negative");
+ }
+
+ if (certificateSubject == null) {
+ certificateSubject = DEFAULT_CERT_SUBJECT;
+ }
+ if (certificateNotBefore == null) {
+ certificateNotBefore = DEFAULT_CERT_NOT_BEFORE;
+ }
+ if (certificateNotAfter == null) {
+ certificateNotAfter = DEFAULT_CERT_NOT_AFTER;
+ }
+ if (certificateSerialNumber == null) {
+ certificateSerialNumber = DEFAULT_CERT_SERIAL_NUMBER;
+ }
+
+ if (certificateNotAfter.before(certificateNotBefore)) {
+ throw new IllegalArgumentException("certificateNotAfter < certificateNotBefore");
+ }
+
+ mKeystoreAlias = keyStoreAlias;
+ mKeySize = keySize;
+ mSpec = spec;
+ mCertificateSubject = certificateSubject;
+ mCertificateSerialNumber = certificateSerialNumber;
+ mCertificateNotBefore = certificateNotBefore;
+ mCertificateNotAfter = certificateNotAfter;
+ mFlags = flags;
+ mKeyValidityStart = keyValidityStart;
+ mKeyValidityForOriginationEnd = keyValidityForOriginationEnd;
+ mKeyValidityForConsumptionEnd = keyValidityForConsumptionEnd;
+ mPurposes = purposes;
+ mDigests = ArrayUtils.cloneIfNotEmpty(digests);
+ mEncryptionPaddings =
+ ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(encryptionPaddings));
+ mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(signaturePaddings));
+ mBlockModes = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(blockModes));
+ mRandomizedEncryptionRequired = randomizedEncryptionRequired;
+ mUserAuthenticationRequired = userAuthenticationRequired;
+ mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
+ }
+
+ /**
+ * Returns the alias that will be used in the {@code java.security.KeyStore}
+ * in conjunction with the {@code AndroidKeyStore}.
+ */
+ public String getKeystoreAlias() {
+ return mKeystoreAlias;
+ }
+
+ /**
+ * Returns the requested key size or {@code -1} if default size should be used.
+ */
+ public int getKeySize() {
+ return mKeySize;
+ }
+
+ /**
+ * Returns the {@link AlgorithmParameterSpec} that will be used for creation
+ * of the key pair.
+ */
+ @NonNull
+ public AlgorithmParameterSpec getAlgorithmParameterSpec() {
+ return mSpec;
+ }
+
+ /**
+ * Returns the subject distinguished name to be used on the X.509 certificate that will be put
+ * in the {@link java.security.KeyStore}.
+ */
+ @NonNull
+ public X500Principal getCertificateSubject() {
+ return mCertificateSubject;
+ }
+
+ /**
+ * Returns the serial number to be used on the X.509 certificate that will be put in the
+ * {@link java.security.KeyStore}.
+ */
+ @NonNull
+ public BigInteger getCertificateSerialNumber() {
+ return mCertificateSerialNumber;
+ }
+
+ /**
+ * Returns the start date to be used on the X.509 certificate that will be put in the
+ * {@link java.security.KeyStore}.
+ */
+ @NonNull
+ public Date getCertificateNotBefore() {
+ return mCertificateNotBefore;
+ }
+
+ /**
+ * Returns the end date to be used on the X.509 certificate that will be put in the
+ * {@link java.security.KeyStore}.
+ */
+ @NonNull
+ public Date getCertificateNotAfter() {
+ return mCertificateNotAfter;
+ }
+
+ /**
+ * @hide
+ */
+ public int getFlags() {
+ return mFlags;
+ }
+
+ /**
+ * Returns {@code true} if the key must be encrypted at rest. This will protect the key with the
+ * secure lock screen credential (e.g., password, PIN, or pattern).
+ *
+ *
+ *
+ *
+ *
+ *
+ *
+ * Example: Symmetric Key
- * The following example illustrates how to obtain a {@link KeyStoreKeySpec} describing the provided
- * Android KeyStore {@link SecretKey}.
+ * The following example illustrates how to obtain a {@code KeyInfo} describing the provided Android
+ * Keystore {@link SecretKey}.
* {@code
- * SecretKey key = ...; // Android KeyStore key
+ * SecretKey key = ...; // Android Keystore key
*
* SecretKeyFactory factory = SecretKeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
- * KeyStoreKeySpec spec;
+ * KeyInfo keyInfo;
* try {
- * spec = (KeyStoreKeySpec) factory.getKeySpec(key, KeyStoreKeySpec.class);
+ * keyInfo = (KeyInfo) factory.getKeySpec(key, KeyInfo.class);
* } catch (InvalidKeySpecException e) {
* // Not an Android KeyStore key.
* }
* }
*
* Example: Private Key
- * The following example illustrates how to obtain a {@link KeyStoreKeySpec} describing the provided
+ * The following example illustrates how to obtain a {@code KeyInfo} describing the provided
* Android KeyStore {@link PrivateKey}.
* {@code
* PrivateKey key = ...; // Android KeyStore key
*
* KeyFactory factory = KeyFactory.getInstance(key.getAlgorithm(), "AndroidKeyStore");
- * KeyStoreKeySpec spec;
+ * KeyInfo keyInfo;
* try {
- * spec = factory.getKeySpec(key, KeyStoreKeySpec.class);
+ * keyInfo = factory.getKeySpec(key, KeyInfo.class);
* } catch (InvalidKeySpecException e) {
* // Not an Android KeyStore key.
* }
* }
*/
-public class KeyStoreKeySpec implements KeySpec {
+public class KeyInfo implements KeySpec {
private final String mKeystoreAlias;
private final int mKeySize;
private final boolean mInsideSecureHardware;
- private final @KeyStoreKeyProperties.OriginEnum int mOrigin;
+ private final @KeyProperties.OriginEnum int mOrigin;
private final Date mKeyValidityStart;
private final Date mKeyValidityForOriginationEnd;
private final Date mKeyValidityForConsumptionEnd;
- private final @KeyStoreKeyProperties.PurposeEnum int mPurposes;
- private final @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
- private final @KeyStoreKeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
- private final @KeyStoreKeyProperties.DigestEnum String[] mDigests;
- private final @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes;
+ private final @KeyProperties.PurposeEnum int mPurposes;
+ private final @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
+ private final @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
+ private final @KeyProperties.DigestEnum String[] mDigests;
+ private final @KeyProperties.BlockModeEnum String[] mBlockModes;
private final boolean mUserAuthenticationRequired;
private final int mUserAuthenticationValidityDurationSeconds;
private final boolean mUserAuthenticationRequirementEnforcedBySecureHardware;
@@ -83,18 +84,18 @@ public class KeyStoreKeySpec implements KeySpec {
/**
* @hide
*/
- KeyStoreKeySpec(String keystoreKeyAlias,
+ public KeyInfo(String keystoreKeyAlias,
boolean insideSecureHardware,
- @KeyStoreKeyProperties.OriginEnum int origin,
+ @KeyProperties.OriginEnum int origin,
int keySize,
Date keyValidityStart,
Date keyValidityForOriginationEnd,
Date keyValidityForConsumptionEnd,
- @KeyStoreKeyProperties.PurposeEnum int purposes,
- @KeyStoreKeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
- @KeyStoreKeyProperties.SignaturePaddingEnum String[] signaturePaddings,
- @KeyStoreKeyProperties.DigestEnum String[] digests,
- @KeyStoreKeyProperties.BlockModeEnum String[] blockModes,
+ @KeyProperties.PurposeEnum int purposes,
+ @KeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
+ @KeyProperties.SignaturePaddingEnum String[] signaturePaddings,
+ @KeyProperties.DigestEnum String[] digests,
+ @KeyProperties.BlockModeEnum String[] blockModes,
boolean userAuthenticationRequired,
int userAuthenticationValidityDurationSeconds,
boolean userAuthenticationRequirementEnforcedBySecureHardware) {
@@ -135,9 +136,9 @@ public class KeyStoreKeySpec implements KeySpec {
}
/**
- * Gets the origin of the key. See {@link KeyStoreKeyProperties}.{@code ORIGIN} constants.
+ * Gets the origin of the key. See {@link KeyProperties}.{@code ORIGIN} constants.
*/
- public @KeyStoreKeyProperties.OriginEnum int getOrigin() {
+ public @KeyProperties.OriginEnum int getOrigin() {
return mOrigin;
}
@@ -182,9 +183,9 @@ public class KeyStoreKeySpec implements KeySpec {
* Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.
* Attempts to use the key for any other purpose will be rejected.
*
- * Example
- * The following example illustrates how to generate an HMAC key in the Android KeyStore under alias
- * {@code key1} authorized to be used only for HMAC with SHA-256 digest and only if the user has
- * been authenticated within the last five minutes.
+ * Example: Symmetric Key
+ * The following example illustrates how to import an AES key into the Android KeyStore under alias
+ * {@code key1} authorized to be used only for encryption/decryption in CBC mode with PKCS#7
+ * padding. The key must export its key material via {@link Key#getEncoded()} in {@code RAW} format.
* {@code
- * KeyGenerator keyGenerator = KeyGenerator.getInstance(
- * KeyStoreKeyProperties.KEY_ALGORITHM_HMAC_SHA256,
- * "AndroidKeyStore");
- * keyGenerator.initialize(
- * new KeyGeneratorSpec.Builder(context)
- * .setAlias("key1")
- * .setPurposes(KeyStoreKeyProperties.PURPOSE_SIGN
- * | KeyStoreKeyProperties.PURPOSE_VERIFY)
- * // Only permit this key to be used if the user authenticated
- * // within the last five minutes.
- * .setUserAuthenticationRequired(true)
- * .setUserAuthenticationValidityDurationSeconds(5 * 60)
- * .build());
- * SecretKey key = keyGenerator.generateKey();
+ * SecretKey key = ...; // AES key
*
- * // The key can also be obtained from the Android KeyStore any time as follows:
* KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
* keyStore.load(null);
- * SecretKey key = (SecretKey) keyStore.getKey("key1", null);
+ * keyStore.setEntry(
+ * "key1",
+ * new KeyStore.SecretKeyEntry(key),
+ * new KeyProtection.Builder(KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
+ * .setBlockMode(KeyProperties.BLOCK_MODE_CBC)
+ * .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_PKCS7)
+ * .build());
+ * // Key imported, obtain a reference to it.
+ * SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
+ * // The original key can now be thrown away.
+ * }
+ *
+ * Example: Asymmetric Key Pair
+ * The following example illustrates how to import an EC key pair into the Android KeyStore under
+ * alias {@code key2} authorized to be used only for signing with SHA-256 digest and only if
+ * the user has been authenticated within the last ten minutes. Both the private and the public key
+ * must export their key material via {@link Key#getEncoded()} in {@code PKCS#8} and {@code X.509}
+ * format respectively.
+ * {@code
+ * PrivateKey privateKey = ...; // EC private key
+ * Certificate[] certChain = ...; // Certificate chain with the first certificate
+ * // containing the corresponding EC public key.
+ *
+ * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
+ * keyStore.load(null);
+ * keyStore.setEntry(
+ * "key2",
+ * new KeyStore.PrivateKeyEntry(privateKey, certChain),
+ * new KeyProtection.Builder(KeyProperties.PURPOSE_SIGN)
+ * .setDigests(KeyProperties.DIGEST_SHA256)
+ * // Only permit this key to be used if the user
+ * // authenticated within the last ten minutes.
+ * .setUserAuthenticationRequired(true)
+ * .setUserAuthenticationValidityDurationSeconds(10 * 60)
+ * .build());
+ * // Key pair imported, obtain a reference to it.
+ * PrivateKey keyStorePrivateKey = (PrivateKey) keyStore.getKey("key2", null);
+ * PublicKey publicKey = keyStore.getCertificate("key2").getPublicKey();
+ * // The original private key can now be thrown away.
* }
*/
-public class KeyGeneratorSpec implements AlgorithmParameterSpec {
-
- private final Context mContext;
- private final String mKeystoreAlias;
+public final class KeyProtection implements ProtectionParameter {
private final int mFlags;
- private final int mKeySize;
private final Date mKeyValidityStart;
private final Date mKeyValidityForOriginationEnd;
private final Date mKeyValidityForConsumptionEnd;
- private final @KeyStoreKeyProperties.PurposeEnum int mPurposes;
- private final @KeyStoreKeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
- private final @KeyStoreKeyProperties.BlockModeEnum String[] mBlockModes;
+ private final @KeyProperties.PurposeEnum int mPurposes;
+ private final @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
+ private final @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
+ private final @KeyProperties.DigestEnum String[] mDigests;
+ private final @KeyProperties.BlockModeEnum String[] mBlockModes;
private final boolean mRandomizedEncryptionRequired;
private final boolean mUserAuthenticationRequired;
private final int mUserAuthenticationValidityDurationSeconds;
- private KeyGeneratorSpec(
- Context context,
- String keyStoreAlias,
+ private KeyProtection(
int flags,
- int keySize,
Date keyValidityStart,
Date keyValidityForOriginationEnd,
Date keyValidityForConsumptionEnd,
- @KeyStoreKeyProperties.PurposeEnum int purposes,
- @KeyStoreKeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
- @KeyStoreKeyProperties.BlockModeEnum String[] blockModes,
+ @KeyProperties.PurposeEnum int purposes,
+ @KeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
+ @KeyProperties.SignaturePaddingEnum String[] signaturePaddings,
+ @KeyProperties.DigestEnum String[] digests,
+ @KeyProperties.BlockModeEnum String[] blockModes,
boolean randomizedEncryptionRequired,
boolean userAuthenticationRequired,
int userAuthenticationValidityDurationSeconds) {
- if (context == null) {
- throw new IllegalArgumentException("context == null");
- } else if (TextUtils.isEmpty(keyStoreAlias)) {
- throw new IllegalArgumentException("keyStoreAlias must not be empty");
- } else if ((userAuthenticationValidityDurationSeconds < 0)
+ if ((userAuthenticationValidityDurationSeconds < 0)
&& (userAuthenticationValidityDurationSeconds != -1)) {
throw new IllegalArgumentException(
"userAuthenticationValidityDurationSeconds must not be negative");
}
- mContext = context;
- mKeystoreAlias = keyStoreAlias;
mFlags = flags;
- mKeySize = keySize;
mKeyValidityStart = keyValidityStart;
mKeyValidityForOriginationEnd = keyValidityForOriginationEnd;
mKeyValidityForConsumptionEnd = keyValidityForConsumptionEnd;
mPurposes = purposes;
mEncryptionPaddings =
ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(encryptionPaddings));
+ mSignaturePaddings =
+ ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(signaturePaddings));
+ mDigests = ArrayUtils.cloneIfNotEmpty(digests);
mBlockModes = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(blockModes));
mRandomizedEncryptionRequired = randomizedEncryptionRequired;
mUserAuthenticationRequired = userAuthenticationRequired;
mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
}
- /**
- * Gets the Android context used for operations with this instance.
- */
- public Context getContext() {
- return mContext;
- }
-
- /**
- * Returns the alias that will be used in the {@code java.security.KeyStore} in conjunction with
- * the {@code AndroidKeyStore}.
- */
- public String getKeystoreAlias() {
- return mKeystoreAlias;
- }
-
/**
* @hide
*/
@@ -155,10 +159,12 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
}
/**
- * Returns the requested key size or {@code -1} if default size should be used.
+ * Returns {@code true} if the {@link java.security.KeyStore} entry must be encrypted at rest.
+ * This will protect the entry with the secure lock screen credential (e.g., password, PIN, or
+ * pattern).
*/
- public int getKeySize() {
- return mKeySize;
+ public boolean isEncryptionAtRestRequired() {
+ return (mFlags & KeyStore.FLAG_ENCRYPTED) != 0;
}
/**
@@ -172,7 +178,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
}
/**
- * Gets the time instant after which the key is no longer valid for decryption and verification.
+ * Gets the time instant after which the key is no long valid for decryption and verification.
*
* @return instant or {@code null} if not restricted.
*/
@@ -182,7 +188,7 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
}
/**
- * Gets the time instant after which the key is no longer valid for encryption and signing.
+ * Gets the time instant after which the key is no long valid for encryption and signing.
*
* @return instant or {@code null} if not restricted.
*/
@@ -195,33 +201,73 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
* Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.
* Attempts to use the key for any other purpose will be rejected.
*
- *
- *
@@ -471,7 +528,11 @@ public class KeyGeneratorSpec implements AlgorithmParameterSpec {
* or a device identifier), consider changing your design to use a random IV which will then
* be provided in addition to the ciphertext to the entities which need to decrypt the
* ciphertext.
+ *
+ *
+ *