/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package android.security.keystore; import android.annotation.IntRange; import android.annotation.NonNull; import android.annotation.Nullable; import android.app.KeyguardManager; import android.hardware.fingerprint.FingerprintManager; import java.security.Key; import java.security.Signature; import java.security.KeyStore.ProtectionParameter; import java.security.cert.Certificate; import java.util.Date; import javax.crypto.Cipher; import javax.crypto.Mac; /** * Specification of how a key or key pair is secured when imported into the * Android Keystore system. This class * specifies authorized uses of the imported key, such as whether user authentication is required * for using the key, what operations the key is authorized for (e.g., decryption, but not signing) * with what parameters (e.g., only with a particular padding scheme or digest), and the key's * validity start and end dates. Key use authorizations expressed in this class apply only to secret * keys and private keys -- public keys can be used for any supported operations. * *

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()}. * *

To help obtain algorithm-specific public parameters of key pairs stored in the Android * Keystore, its private keys implement {@link java.security.interfaces.ECKey} or * {@link java.security.interfaces.RSAKey} interfaces whereas its public keys implement * {@link java.security.interfaces.ECPublicKey} or {@link java.security.interfaces.RSAPublicKey} * interfaces. * *

NOTE: The key material of keys stored in the Android Keystore is not accessible. * *

Instances of this class are immutable. * *

Known issues

* A known bug in Android 6.0 (API Level 23) causes user authentication-related authorizations to be * enforced even for public keys. To work around this issue extract the public key material to use * outside of Android Keystore. For example: *
 {@code
 * PublicKey unrestrictedPublicKey =
 *         KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
 *                 new X509EncodedKeySpec(publicKey.getEncoded()));
 * }
* *

Example: AES key for encryption/decryption in GCM mode

* This 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 GCM mode with no padding. * The key must export its key material via {@link Key#getEncoded()} in {@code RAW} format. *
 {@code
 * SecretKey key = ...; // AES key
 *
 * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
 * keyStore.load(null);
 * keyStore.setEntry(
 *         "key1",
 *         new KeyStore.SecretKeyEntry(key),
 *         new KeyProtection.Builder(KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
 *                 .setBlockMode(KeyProperties.BLOCK_MODE_GCM)
 *                 .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
 *                 .build());
 * // Key imported, obtain a reference to it.
 * SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
 * // The original key can now be discarded.
 *
 * Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
 * cipher.init(Cipher.ENCRYPT_MODE, keyStoreKey);
 * ...
 * }
* *

Example: HMAC key for generating MACs using SHA-512

* This example illustrates how to import an HMAC key into the Android KeyStore under alias * {@code key1} authorized to be used only for generating MACs using SHA-512 digest. The key must * export its key material via {@link Key#getEncoded()} in {@code RAW} format. *
 {@code
 * SecretKey key = ...; // HMAC key of algorithm "HmacSHA512".
 *
 * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
 * keyStore.load(null);
 * keyStore.setEntry(
 *         "key1",
 *         new KeyStore.SecretKeyEntry(key),
 *         new KeyProtection.Builder(KeyProperties.PURPOSE_SIGN).build());
 * // Key imported, obtain a reference to it.
 * SecretKey keyStoreKey = (SecretKey) keyStore.getKey("key1", null);
 * // The original key can now be discarded.
 *
 * Mac mac = Mac.getInstance("HmacSHA512");
 * mac.init(keyStoreKey);
 * ...
 * }
* *

Example: EC key pair for signing/verification using ECDSA

* This example illustrates how to import an EC key pair into the Android KeyStore under alias * {@code key2} with the private key authorized to be used only for signing with SHA-256 or SHA-512 * digests. The use of the public key is unrestricted. 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, KeyProperties.DIGEST_SHA512)
 *                 .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 discarded.
 *
 * Signature signature = Signature.getInstance("SHA256withECDSA");
 * signature.initSign(keyStorePrivateKey);
 * ...
 * }
* *

Example: RSA key pair for signing/verification using PKCS#1 padding

* This example illustrates how to import an RSA key pair into the Android KeyStore under alias * {@code key2} with the private key authorized to be used only for signing using the PKCS#1 * signature padding scheme with SHA-256 digest and only if the user has been authenticated within * the last ten minutes. The use of the public key is unrestricted (see Known Issues). 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 = ...;   // RSA private key
 * Certificate[] certChain = ...; // Certificate chain with the first certificate
 *                                // containing the corresponding RSA 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)
 *                 .setSignaturePaddings(KeyProperties.SIGNATURE_PADDING_RSA_PKCS1)
 *                 // 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 discarded.
 *
 * Signature signature = Signature.getInstance("SHA256withRSA");
 * signature.initSign(keyStorePrivateKey);
 * ...
 * }
* *

Example: RSA key pair for encryption/decryption using PKCS#1 padding

* This example illustrates how to import an RSA key pair into the Android KeyStore under alias * {@code key2} with the private key authorized to be used only for decryption using the PKCS#1 * encryption padding scheme. The use of public key is unrestricted, thus permitting encryption * using any padding schemes and digests. 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 = ...;   // RSA private key
 * Certificate[] certChain = ...; // Certificate chain with the first certificate
 *                                // containing the corresponding RSA public key.
 *
 * KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
 * keyStore.load(null);
 * keyStore.setEntry(
 *         "key2",
 *         new KeyStore.PrivateKeyEntry(privateKey, certChain),
 *         new KeyProtection.Builder(KeyProperties.PURPOSE_DECRYPT)
 *                 .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1)
 *                 .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 discarded.
 *
 * Cipher cipher = Cipher.getInstance("RSA/ECB/PKCS1Padding");
 * cipher.init(Cipher.DECRYPT_MODE, keyStorePrivateKey);
 * ...
 * }
*/ public final class KeyProtection implements ProtectionParameter { private final Date mKeyValidityStart; private final Date mKeyValidityForOriginationEnd; private final Date mKeyValidityForConsumptionEnd; 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 final boolean mUserAuthenticationValidWhileOnBody; private final boolean mInvalidatedByBiometricEnrollment; private KeyProtection( Date keyValidityStart, Date keyValidityForOriginationEnd, Date keyValidityForConsumptionEnd, @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, boolean userAuthenticationValidWhileOnBody, boolean invalidatedByBiometricEnrollment) { mKeyValidityStart = Utils.cloneIfNotNull(keyValidityStart); mKeyValidityForOriginationEnd = Utils.cloneIfNotNull(keyValidityForOriginationEnd); mKeyValidityForConsumptionEnd = Utils.cloneIfNotNull(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; mUserAuthenticationValidWhileOnBody = userAuthenticationValidWhileOnBody; mInvalidatedByBiometricEnrollment = invalidatedByBiometricEnrollment; } /** * 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 Utils.cloneIfNotNull(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 Utils.cloneIfNotNull(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 Utils.cloneIfNotNull(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 KeyProperties}.{@code PURPOSE} flags. */ public @KeyProperties.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 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 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 GCM}, {@code CBC}) 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 the key is authorized to be used only if the user has been * authenticated. * *

This authorization applies only to secret key and private key operations. Public key * operations are not restricted. * * @see #getUserAuthenticationValidityDurationSeconds() * @see Builder#setUserAuthenticationRequired(boolean) */ public boolean isUserAuthenticationRequired() { return mUserAuthenticationRequired; } /** * Gets the duration of time (seconds) for which this key is authorized to be used after the * user is successfully authenticated. This has effect only if user authentication is required * (see {@link #isUserAuthenticationRequired()}). * *

This authorization applies only to secret key and 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() * @see Builder#setUserAuthenticationValidityDurationSeconds(int) */ public int getUserAuthenticationValidityDurationSeconds() { return mUserAuthenticationValidityDurationSeconds; } /** * Returns {@code true} if the key will be de-authorized when the device is removed from the * user's body. This option has no effect on keys that don't have an authentication validity * duration, and has no effect if the device lacks an on-body sensor. * *

Authorization applies only to secret key and private key operations. Public key operations * are not restricted. * * @see #isUserAuthenticationRequired() * @see #getUserAuthenticationValidityDurationSeconds() * @see Builder#setUserAuthenticationValidWhileOnBody(boolean) */ public boolean isUserAuthenticationValidWhileOnBody() { return mUserAuthenticationValidWhileOnBody; } /** * Returns {@code true} if the key is irreversibly invalidated when a new fingerprint is * enrolled or all enrolled fingerprints are removed. This has effect only for keys that * require fingerprint user authentication for every use. * * @see #isUserAuthenticationRequired() * @see #getUserAuthenticationValidityDurationSeconds() * @see Builder#setInvalidatedByBiometricEnrollment(boolean) */ public boolean isInvalidatedByBiometricEnrollment() { return mInvalidatedByBiometricEnrollment; } /** * Builder of {@link KeyProtection} instances. */ public final static class Builder { private @KeyProperties.PurposeEnum int mPurposes; private Date mKeyValidityStart; private Date mKeyValidityForOriginationEnd; private Date mKeyValidityForConsumptionEnd; 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; private boolean mUserAuthenticationValidWhileOnBody; private boolean mInvalidatedByBiometricEnrollment = true; /** * 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. * *

See {@link KeyProperties}.{@code PURPOSE} flags. */ public Builder(@KeyProperties.PurposeEnum int purposes) { mPurposes = purposes; } /** * Sets the time instant before which the key is not yet valid. * *

By default, the key is valid at any instant. * * @see #setKeyValidityEnd(Date) */ @NonNull public Builder setKeyValidityStart(Date startDate) { mKeyValidityStart = Utils.cloneIfNotNull(startDate); return this; } /** * Sets the time instant after which the key is no longer valid. * *

By default, the key is valid at any instant. * * @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. * * @see #setKeyValidityForConsumptionEnd(Date) */ @NonNull public Builder setKeyValidityForOriginationEnd(Date endDate) { mKeyValidityForOriginationEnd = Utils.cloneIfNotNull(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. * * @see #setKeyValidityForOriginationEnd(Date) */ @NonNull public Builder setKeyValidityForConsumptionEnd(Date endDate) { mKeyValidityForConsumptionEnd = Utils.cloneIfNotNull(endDate); 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. * *

For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it * is usually necessary to authorize the use of no/any padding * ({@link KeyProperties#ENCRYPTION_PADDING_NONE}) and/or PKCS#1 encryption padding * ({@link KeyProperties#ENCRYPTION_PADDING_RSA_PKCS1}). This is because RSA decryption is * required by some cipher suites, and some stacks request decryption using no padding * whereas others request PKCS#1 padding. * *

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. * *

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. Attempts to use the key with any other digest algorithm will be * rejected. * *

This must be specified for signing/verification keys and RSA encryption/decryption * keys used with RSA OAEP padding scheme because these operations involve a digest. For * HMAC keys, the default is the digest specified in {@link Key#getAlgorithm()} (e.g., * {@code SHA-256} for key algorithm {@code HmacSHA256}). HMAC keys cannot be authorized * for more than one digest. * *

For private keys used for TLS/SSL client or server authentication it is usually * necessary to authorize the use of no digest ({@link KeyProperties#DIGEST_NONE}). This is * because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use * a private key to sign it. * *

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 GCM}, {@code CBC}) 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 symmetric encryption/decryption keys. * *

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: *