Most visited

Recently visited

Added in API level 23

KeyProtection

public final class KeyProtection
extends Object implements KeyStore.ProtectionParameter

java.lang.Object
   ↳ android.security.keystore.KeyProtection


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 KeyProtection.Builder and pass the instance into KeyStore.setEntry with the key or key pair being imported.

To obtain the secret/symmetric or private key from the Android Keystore use KeyStore.getKey(String, null) or KeyStore.getEntry(String, null). To obtain the public key from the Android Keystore use getCertificate(String) and then getPublicKey().

To help obtain algorithm-specific public parameters of key pairs stored in the Android Keystore, its private keys implement ECKey or RSAKey interfaces whereas its public keys implement ECPublicKey or 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:
 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 key1 authorized to be used only for encryption/decryption in GCM mode with no padding. The key must export its key material via getEncoded() in RAW format.
 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 key1 authorized to be used only for generating MACs using SHA-512 digest. The key must export its key material via getEncoded() in RAW format.
 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 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 getEncoded() in PKCS#8 and X.509 format respectively.
 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 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 getEncoded() in PKCS#8 and X.509 format respectively.
 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 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 getEncoded() in PKCS#8 and X.509 format respectively.
 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);
 ...
 

Summary

Nested classes

class KeyProtection.Builder

Builder of KeyProtection instances. 

Public methods

String[] getBlockModes()

Gets the set of block modes (e.g., GCM, CBC) with which the key can be used when encrypting/decrypting.

String[] getDigests()

Gets the set of digest algorithms (e.g., SHA-256, SHA-384) with which the key can be used.

String[] getEncryptionPaddings()

Gets the set of padding schemes (e.g., PKCS7Padding, PKCS1Padding, NoPadding) with which the key can be used when encrypting/decrypting.

Date getKeyValidityForConsumptionEnd()

Gets the time instant after which the key is no long valid for decryption and verification.

Date getKeyValidityForOriginationEnd()

Gets the time instant after which the key is no long valid for encryption and signing.

Date getKeyValidityStart()

Gets the time instant before which the key is not yet valid.

int getPurposes()

Gets the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.

String[] getSignaturePaddings()

Gets the set of padding schemes (e.g., PSS, PKCS#1) with which the key can be used when signing/verifying.

int getUserAuthenticationValidityDurationSeconds()

Gets the duration of time (seconds) for which this key is authorized to be used after the user is successfully authenticated.

boolean isDigestsSpecified()

Returns true if the set of digest algorithms with which the key can be used has been specified.

boolean isInvalidatedByBiometricEnrollment()

Returns true if the key is irreversibly invalidated when a new fingerprint is enrolled or all enrolled fingerprints are removed.

boolean isRandomizedEncryptionRequired()

Returns true if encryption using this key must be sufficiently randomized to produce different ciphertexts for the same plaintext every time.

boolean isUserAuthenticationRequired()

Returns true if the key is authorized to be used only if the user has been authenticated.

boolean isUserAuthenticationValidWhileOnBody()

Returns true if the key will be de-authorized when the device is removed from the user's body.

Inherited methods

From class java.lang.Object

Public methods

getBlockModes

Added in API level 23
String[] getBlockModes ()

Gets the set of block modes (e.g., GCM, 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 KeyProperties.BLOCK_MODE constants.

Returns
String[]

getDigests

Added in API level 23
String[] getDigests ()

Gets the set of digest algorithms (e.g., SHA-256, SHA-384) with which the key can be used.

See KeyProperties.DIGEST constants.

Returns
String[]
Throws
IllegalStateException if this set has not been specified.

See also:

getEncryptionPaddings

Added in API level 23
String[] getEncryptionPaddings ()

Gets the set of padding schemes (e.g., PKCS7Padding, PKCS1Padding, 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 KeyProperties.ENCRYPTION_PADDING constants.

Returns
String[]

getKeyValidityForConsumptionEnd

Added in API level 23
Date getKeyValidityForConsumptionEnd ()

Gets the time instant after which the key is no long valid for decryption and verification.

Returns
Date instant or null if not restricted.

getKeyValidityForOriginationEnd

Added in API level 23
Date getKeyValidityForOriginationEnd ()

Gets the time instant after which the key is no long valid for encryption and signing.

Returns
Date instant or null if not restricted.

getKeyValidityStart

Added in API level 23
Date getKeyValidityStart ()

Gets the time instant before which the key is not yet valid.

Returns
Date instant or null if not restricted.

getPurposes

Added in API level 23
int getPurposes ()

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 KeyProperties.PURPOSE flags.

Returns
int

getSignaturePaddings

Added in API level 23
String[] getSignaturePaddings ()

Gets the set of padding schemes (e.g., PSS, 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 KeyProperties.SIGNATURE_PADDING constants.

Returns
String[]

getUserAuthenticationValidityDurationSeconds

Added in API level 23
int getUserAuthenticationValidityDurationSeconds ()

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 isUserAuthenticationRequired()).

This authorization applies only to secret key and private key operations. Public key operations are not restricted.

Returns
int duration in seconds or -1 if authentication is required for every use of the key.

See also:

isDigestsSpecified

Added in API level 23
boolean isDigestsSpecified ()

Returns true if the set of digest algorithms with which the key can be used has been specified.

Returns
boolean

See also:

isInvalidatedByBiometricEnrollment

Added in API level 24
boolean isInvalidatedByBiometricEnrollment ()

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

Returns
boolean

See also:

isRandomizedEncryptionRequired

Added in API level 23
boolean isRandomizedEncryptionRequired ()

Returns 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 (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.

Returns
boolean

isUserAuthenticationRequired

Added in API level 23
boolean isUserAuthenticationRequired ()

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

Returns
boolean

See also:

isUserAuthenticationValidWhileOnBody

Added in API level 24
boolean isUserAuthenticationValidWhileOnBody ()

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

Returns
boolean

See also: