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. * *
{@code
* PublicKey unrestrictedPublicKey =
* KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
* new X509EncodedKeySpec(publicKey.getEncoded()));
* }
*
* {@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);
* ...
* }
*
* {@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);
* ...
* }
*
* {@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);
* ...
* }
*
* {@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);
* ...
* }
*
* {@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, UserAuthArgs {
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 @KeyProperties.AuthEnum int mUserAuthenticationType;
private final int mUserAuthenticationValidityDurationSeconds;
private final boolean mUserPresenceRequred;
private final boolean mUserAuthenticationValidWhileOnBody;
private final boolean mInvalidatedByBiometricEnrollment;
private final long mBoundToSecureUserId;
private final boolean mCriticalToDeviceEncryption;
private final boolean mUserConfirmationRequired;
private final boolean mUnlockedDeviceRequired;
private final boolean mIsStrongBoxBacked;
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,
@KeyProperties.AuthEnum int userAuthenticationType,
int userAuthenticationValidityDurationSeconds,
boolean userPresenceRequred,
boolean userAuthenticationValidWhileOnBody,
boolean invalidatedByBiometricEnrollment,
long boundToSecureUserId,
boolean criticalToDeviceEncryption,
boolean userConfirmationRequired,
boolean unlockedDeviceRequired,
boolean isStrongBoxBacked) {
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;
mUserAuthenticationType = userAuthenticationType;
mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
mUserPresenceRequred = userPresenceRequred;
mUserAuthenticationValidWhileOnBody = userAuthenticationValidWhileOnBody;
mInvalidatedByBiometricEnrollment = invalidatedByBiometricEnrollment;
mBoundToSecureUserId = boundToSecureUserId;
mCriticalToDeviceEncryption = criticalToDeviceEncryption;
mUserConfirmationRequired = userConfirmationRequired;
mUnlockedDeviceRequired = unlockedDeviceRequired;
mIsStrongBoxBacked = isStrongBoxBacked;
}
/**
* 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; } /** * Returns {@code true} if the key is authorized to be used only for messages confirmed by the * user. * * Confirmation is separate from user authentication (see * {@link #isUserAuthenticationRequired()}). Keys can be created that require confirmation but * not user authentication, or user authentication but not confirmation, or both. Confirmation * verifies that some user with physical possession of the device has approved a displayed * message. User authentication verifies that the correct user is present and has * authenticated. * *
This authorization applies only to secret key and private key operations. Public key * operations are not restricted. * * @see Builder#setUserConfirmationRequired(boolean) */ public boolean isUserConfirmationRequired() { return mUserConfirmationRequired; } public @KeyProperties.AuthEnum int getUserAuthenticationType() { return mUserAuthenticationType; } /** * 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 is authorized to be used only if a test of user presence has * been performed between the {@code Signature.initSign()} and {@code Signature.sign()} calls. * It requires that the KeyStore implementation have a direct way to validate the user presence * for example a KeyStore hardware backed strongbox can use a button press that is observable * in hardware. A test for user presence is tangential to authentication. The test can be part * of an authentication step as long as this step can be validated by the hardware protecting * the key and cannot be spoofed. For example, a physical button press can be used as a test of * user presence if the other pins connected to the button are not able to simulate a button * press. There must be no way for the primary processor to fake a button press, or that * button must not be used as a test of user presence. */ public boolean isUserPresenceRequired() { return mUserPresenceRequred; } /** * 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 biometric is * enrolled or all enrolled biometrics are removed. This has effect only for keys that * require biometric user authentication for every use. * * @see #isUserAuthenticationRequired() * @see #getUserAuthenticationValidityDurationSeconds() * @see Builder#setInvalidatedByBiometricEnrollment(boolean) */ public boolean isInvalidatedByBiometricEnrollment() { return mInvalidatedByBiometricEnrollment; } /** * Return the secure user id that this key should be bound to. * * Normally an authentication-bound key is tied to the secure user id of the current user * (either the root SID from GateKeeper for auth-bound keys with a timeout, or the authenticator * id of the current biometric set for keys requiring explicit biometric authorization). * If this parameter is set (this method returning non-zero value), the key should be tied to * the specified secure user id, overriding the logic above. * * This is only applicable when {@link #isUserAuthenticationRequired} is {@code true} * * @see KeymasterUtils#addUserAuthArgs * @hide */ @TestApi public long getBoundToSpecificSecureUserId() { return mBoundToSecureUserId; } /** * Return whether this key is critical to the device encryption flow. * * @see android.security.KeyStore#FLAG_CRITICAL_TO_DEVICE_ENCRYPTION * @hide */ public boolean isCriticalToDeviceEncryption() { return mCriticalToDeviceEncryption; } /** * Returns {@code true} if the screen must be unlocked for this key to be used for decryption or * signing. Encryption and signature verification will still be available when the screen is * locked. * * @see Builder#setUnlockedDeviceRequired(boolean) */ public boolean isUnlockedDeviceRequired() { return mUnlockedDeviceRequired; } /** * Returns {@code true} if the key is protected by a Strongbox security chip. * @hide */ public boolean isStrongBoxBacked() { return mIsStrongBoxBacked; } /** * 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 = 0; private @KeyProperties.AuthEnum int mUserAuthenticationType = KeyProperties.AUTH_BIOMETRIC_STRONG; private boolean mUserPresenceRequired = false; private boolean mUserAuthenticationValidWhileOnBody; private boolean mInvalidatedByBiometricEnrollment = true; private boolean mUserConfirmationRequired; private boolean mUnlockedDeviceRequired = false; private long mBoundToSecureUserId = GateKeeper.INVALID_SECURE_USER_ID; private boolean mCriticalToDeviceEncryption = false; private boolean mIsStrongBoxBacked = false; /** * 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: *
Before disabling this requirement, consider the following approaches instead: *
By default, the key is authorized to be used regardless of whether the user has been * authenticated. * *
When user authentication is required: *
This authorization applies only to secret key and private key operations. Public key * operations are not restricted. * * @see #setUserAuthenticationValidityDurationSeconds(int) * @see KeyguardManager#isDeviceSecure() * @see BiometricManager#canAuthenticate() */ @NonNull public Builder setUserAuthenticationRequired(boolean required) { mUserAuthenticationRequired = required; return this; } /** * Sets whether this key is authorized to be used only for messages confirmed by the * user. * * Confirmation is separate from user authentication (see * {@link #setUserAuthenticationRequired(boolean)}). Keys can be created that require * confirmation but not user authentication, or user authentication but not confirmation, * or both. Confirmation verifies that some user with physical possession of the device has * approved a displayed message. User authentication verifies that the correct user is * present and has authenticated. * *
This authorization applies only to secret key and private key operations. Public key * operations are not restricted. * * See {@link android.security.ConfirmationPrompt} class for * more details about user confirmations. */ @NonNull public Builder setUserConfirmationRequired(boolean required) { mUserConfirmationRequired = required; return this; } /** * Sets the duration of time (seconds) for which this key is authorized to be used after the * user is successfully authenticated. This has effect if the key requires user * authentication for its use (see {@link #setUserAuthenticationRequired(boolean)}). * *
By default, if user authentication is required, it must take place for every use of * the key. * *
Cryptographic operations involving keys which require user authentication to take * place for every operation can only use biometric authentication. This is achieved by * initializing a cryptographic operation ({@link Signature}, {@link Cipher}, {@link Mac}) * with the key, wrapping it into a {@link BiometricPrompt.CryptoObject}, invoking * {@code BiometricPrompt.authenticate} with {@code CryptoObject}, and proceeding with * the cryptographic operation only if the authentication flow succeeds. * *
Cryptographic operations involving keys which are authorized to be used for a duration * of time after a successful user authentication event can only use secure lock screen * authentication. These cryptographic operations will throw * {@link UserNotAuthenticatedException} during initialization if the user needs to be * authenticated to proceed. This situation can be resolved by the user unlocking the secure * lock screen of the Android or by going through the confirm credential flow initiated by * {@link KeyguardManager#createConfirmDeviceCredentialIntent(CharSequence, CharSequence)}. * Once resolved, initializing a new cryptographic operation using this key (or any other * key which is authorized to be used for a fixed duration of time after user * authentication) should succeed provided the user authentication flow completed * successfully. * * @param seconds duration in seconds or {@code -1} if user authentication must take place * for every use of the key. * * @see #setUserAuthenticationRequired(boolean) * @see BiometricPrompt * @see BiometricPrompt.CryptoObject * @see KeyguardManager * @deprecated See {@link #setUserAuthenticationParameters(int, int)} */ @Deprecated @NonNull public Builder setUserAuthenticationValidityDurationSeconds( @IntRange(from = -1) int seconds) { if (seconds < -1) { throw new IllegalArgumentException("seconds must be -1 or larger"); } if (seconds == -1) { return setUserAuthenticationParameters(0, KeyProperties.AUTH_BIOMETRIC_STRONG); } return setUserAuthenticationParameters(seconds, KeyProperties.AUTH_DEVICE_CREDENTIAL | KeyProperties.AUTH_BIOMETRIC_STRONG); } /** * Sets the duration of time (seconds) and authorization type for which this key is * authorized to be used after the user is successfully authenticated. This has effect if * the key requires user authentication for its use (see * {@link #setUserAuthenticationRequired(boolean)}). * *
By default, if user authentication is required, it must take place for every use of * the key. * *
These cryptographic operations will throw {@link UserNotAuthenticatedException} during * initialization if the user needs to be authenticated to proceed. This situation can be * resolved by the user authenticating with the appropriate biometric or credential as * required by the key. See {@link BiometricPrompt.Builder#setAllowedAuthenticators(int)} * and {@link BiometricManager.Authenticators}. * *
Once resolved, initializing a new cryptographic operation using this key (or any other * key which is authorized to be used for a fixed duration of time after user * authentication) should succeed provided the user authentication flow completed * successfully. * * @param timeout duration in seconds or {@code 0} if user authentication must take place * for every use of the key. * @param type set of authentication types which can authorize use of the key. See * {@link KeyProperties}.{@code AUTH} flags. * * @see #setUserAuthenticationRequired(boolean) * @see BiometricPrompt * @see BiometricPrompt.CryptoObject * @see KeyguardManager */ @NonNull public Builder setUserAuthenticationParameters(@IntRange(from = 0) int timeout, @KeyProperties.AuthEnum int type) { if (timeout < 0) { throw new IllegalArgumentException("timeout must be 0 or larger"); } mUserAuthenticationValidityDurationSeconds = timeout; mUserAuthenticationType = type; return this; } /** * Sets whether a test of user presence is required to be performed between the * {@code Signature.initSign()} and {@code Signature.sign()} method calls. It requires that * the KeyStore implementation have a direct way to validate the user presence for example * a KeyStore hardware backed strongbox can use a button press that is observable in * hardware. A test for user presence is tangential to authentication. The test can be part * of an authentication step as long as this step can be validated by the hardware * protecting the key and cannot be spoofed. For example, a physical button press can be * used as a test of user presence if the other pins connected to the button are not able * to simulate a button press. There must be no way for the primary processor to fake a * button press, or that button must not be used as a test of user presence. */ @NonNull public Builder setUserPresenceRequired(boolean required) { mUserPresenceRequired = required; return this; } /** * Sets whether the key will remain authorized only until the device is removed from the * user's body up to the limit of the authentication validity period (see * {@link #setUserAuthenticationValidityDurationSeconds} and * {@link #setUserAuthenticationRequired}). Once the device has been removed from the * user's body, the key will be considered unauthorized and the user will need to * re-authenticate to use it. For keys without an authentication validity period this * parameter has no effect. * *
Similarly, on devices that do not have an on-body sensor, this parameter will have no * effect; the device will always be considered to be "on-body" and the key will therefore * remain authorized until the validity period ends. * * @param remainsValid if {@code true}, and if the device supports on-body detection, key * will be invalidated when the device is removed from the user's body or when the * authentication validity expires, whichever occurs first. */ @NonNull public Builder setUserAuthenticationValidWhileOnBody(boolean remainsValid) { mUserAuthenticationValidWhileOnBody = remainsValid; return this; } /** * Sets whether this key should be invalidated on biometric enrollment. This * applies only to keys which require user authentication (see {@link * #setUserAuthenticationRequired(boolean)}) and if no positive validity duration has been * set (see {@link #setUserAuthenticationValidityDurationSeconds(int)}, meaning the key is * valid for biometric authentication only. * *
By default, {@code invalidateKey} is {@code true}, so keys that are valid for * biometric authentication only are irreversibly invalidated when a new * biometric is enrolled, or when all existing biometrics are deleted. That may be * changed by calling this method with {@code invalidateKey} set to {@code false}. * *
Invalidating keys on enrollment of a new biometric or unenrollment of all biometrics * improves security by ensuring that an unauthorized person who obtains the password can't * gain the use of biometric-authenticated keys by enrolling their own biometric. However, * invalidating keys makes key-dependent operations impossible, requiring some fallback * procedure to authenticate the user and set up a new key. */ @NonNull public Builder setInvalidatedByBiometricEnrollment(boolean invalidateKey) { mInvalidatedByBiometricEnrollment = invalidateKey; return this; } /** * Set the secure user id that this key should be bound to. * * Normally an authentication-bound key is tied to the secure user id of the current user * (either the root SID from GateKeeper for auth-bound keys with a timeout, or the * authenticator id of the current biometric set for keys requiring explicit biometric * authorization). If this parameter is set (this method returning non-zero value), the key * should be tied to the specified secure user id, overriding the logic above. * * This is only applicable when {@link #setUserAuthenticationRequired} is set to * {@code true} * * @see KeyProtection#getBoundToSpecificSecureUserId() * @hide */ @TestApi public Builder setBoundToSpecificSecureUserId(long secureUserId) { mBoundToSecureUserId = secureUserId; return this; } /** * Set whether this key is critical to the device encryption flow * * This is a special flag only available to system servers to indicate the current key * is part of the device encryption flow. * * @see android.security.KeyStore#FLAG_CRITICAL_TO_DEVICE_ENCRYPTION * @hide */ public Builder setCriticalToDeviceEncryption(boolean critical) { mCriticalToDeviceEncryption = critical; return this; } /** * Sets whether the keystore requires the screen to be unlocked before allowing decryption * using this key. If this is set to {@code true}, any attempt to decrypt or sign using this * key while the screen is locked will fail. A locked device requires a PIN, password, * biometric, or other trusted factor to access. While the screen is locked, the key can * still be used for encryption or signature verification. */ @NonNull public Builder setUnlockedDeviceRequired(boolean unlockedDeviceRequired) { mUnlockedDeviceRequired = unlockedDeviceRequired; return this; } /** * Sets whether this key should be protected by a StrongBox security chip. * @hide */ @NonNull public Builder setIsStrongBoxBacked(boolean isStrongBoxBacked) { mIsStrongBoxBacked = isStrongBoxBacked; return this; } /** * Builds an instance of {@link KeyProtection}. * * @throws IllegalArgumentException if a required field is missing */ @NonNull public KeyProtection build() { return new KeyProtection( mKeyValidityStart, mKeyValidityForOriginationEnd, mKeyValidityForConsumptionEnd, mPurposes, mEncryptionPaddings, mSignaturePaddings, mDigests, mBlockModes, mRandomizedEncryptionRequired, mUserAuthenticationRequired, mUserAuthenticationType, mUserAuthenticationValidityDurationSeconds, mUserPresenceRequired, mUserAuthenticationValidWhileOnBody, mInvalidatedByBiometricEnrollment, mBoundToSecureUserId, mCriticalToDeviceEncryption, mUserConfirmationRequired, mUnlockedDeviceRequired, mIsStrongBoxBacked); } } }