KeyProtection

class KeyProtection : KeyStore.ProtectionParameter

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 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 java.security.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 java.security.interfaces.ECKey or java.security.interfaces.RSAKey interfaces whereas its public keys implement java.security.interfaces.ECPublicKey or 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

<code>PublicKey unrestrictedPublicKey =
          KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
                  new X509EncodedKeySpec(publicKey.getEncoded()));
  </code>

Example: AES key for encryption/decryption in GCM mode

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

Example: HMAC key for generating MACs using SHA-512

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

Example: EC key pair for signing/verification using ECDSA

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

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

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

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

<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);
  ...
  </code>

Summary

Public methods

fun getBlockModes(): Array<String!>

fun getDigests(): Array<String!>

fun getEncryptionPaddings(): Array<String!>

fun getKeyValidityForConsumptionEnd(): Date?

fun getKeyValidityForOriginationEnd(): Date?

fun getKeyValidityStart(): Date?

fun getMaxUsageCount(): Int

fun getMgf1Digests(): MutableSet<String!>

fun getPurposes(): Int

fun getSignaturePaddings(): Array<String!>

fun getUserAuthenticationType(): Int

fun getUserAuthenticationValidityDurationSeconds(): Int

fun isDigestsSpecified(): Boolean

fun isInvalidatedByBiometricEnrollment(): Boolean

fun isMgf1DigestsSpecified(): Boolean

fun isRandomizedEncryptionRequired(): Boolean

fun isUnlockedDeviceRequired(): Boolean

fun isUserAuthenticationRequired(): Boolean

fun isUserAuthenticationValidWhileOnBody(): Boolean

fun isUserConfirmationRequired(): Boolean

fun isUserPresenceRequired(): Boolean