public final class KeyProtection extends Object implements KeyStore.ProtectionParameter
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
KeyStore.getCertificate(String)
and then
Certificate.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.
PublicKey unrestrictedPublicKey =
KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
new X509EncodedKeySpec(publicKey.getEncoded()));
key1
authorized to be used only for encryption/decryption in GCM mode with no padding.
The key must export its key material via Key.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);
...
key1
authorized to be used only for generating MACs using SHA-512 digest. The key must
export its key material via Key.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);
...
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 Key.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);
...
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 Key.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);
...
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 Key.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);
...
Modifier and Type | Class and Description |
---|---|
static class |
KeyProtection.Builder
Builder of
KeyProtection instances. |
Modifier and Type | Method and Description |
---|---|
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. |
public Date getKeyValidityStart()
null
if not restricted.public Date getKeyValidityForConsumptionEnd()
null
if not restricted.public Date getKeyValidityForOriginationEnd()
null
if not restricted.public int getPurposes()
See KeyProperties
.PURPOSE
flags.
public String[] getEncryptionPaddings()
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.
public String[] getSignaturePaddings()
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.
public String[] getDigests()
SHA-256
, SHA-384
) with which the key
can be used.
See KeyProperties
.DIGEST
constants.
IllegalStateException
- if this set has not been specified.isDigestsSpecified()
public boolean isDigestsSpecified()
true
if the set of digest algorithms with which the key can be used has been
specified.getDigests()
public String[] getBlockModes()
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.
public boolean isRandomizedEncryptionRequired()
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.public boolean isUserAuthenticationRequired()
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.
public int getUserAuthenticationValidityDurationSeconds()
isUserAuthenticationRequired()
).
This authorization applies only to secret key and private key operations. Public key operations are not restricted.
-1
if authentication is required for every use of the
key.isUserAuthenticationRequired()
,
KeyProtection.Builder.setUserAuthenticationValidityDurationSeconds(int)
public boolean isUserAuthenticationValidWhileOnBody()
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.
public boolean isInvalidatedByBiometricEnrollment()
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.