KeyProtection

Class Overview

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) and with what parameters (e.g., only with a particular padding scheme or digest), the key's and 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.

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 public key is unrestricted, thus permitting signature verification using any 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 = ...;   // 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 public key is unrestricted, thus permitting signature verification using any padding schemes and digests, and without user authentication. 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	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.

[Expand] Inherited Methods

From class java.lang.Object Object clone() Creates and returns a copy of this Object. boolean equals(Object o) Compares this instance with the specified object and indicates if they are equal. void finalize() Invoked when the garbage collector has detected that this instance is no longer reachable. final Class<?> getClass() Returns the unique instance of Class that represents this object's class. int hashCode() Returns an integer hash code for this object. final void notify() Causes a thread which is waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. final void notifyAll() Causes all threads which are waiting on this object's monitor (by means of calling one of the wait() methods) to be woken up. String toString() Returns a string containing a concise, human-readable description of this object. final void wait() Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object. final void wait(long millis, int nanos) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires. final void wait(long millis) Causes the calling thread to wait until another thread calls the notify() or notifyAll() method of this object or until the specified timeout expires.