KeyGenParameterSpec

class KeyGenParameterSpec : AlgorithmParameterSpec

AlgorithmParameterSpec for initializing a KeyPairGenerator or a KeyGenerator of the Android Keystore system. The spec determines authorized uses of the key, such as whether user authentication is required for using the key, what operations are authorized (e.g., signing, but not decryption), 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 the spec apply only to secret keys and private keys -- public keys can be used for any supported operations.

To generate an asymmetric key pair or a symmetric key, create an instance of this class using the Builder, initialize a KeyPairGenerator or a KeyGenerator of the desired key type (e.g., EC or AES -- see KeyProperties.KEY_ALGORITHM constants) from the AndroidKeyStore provider with the KeyGenParameterSpec instance, and then generate a key or key pair using KeyGenerator#generateKey() or KeyPairGenerator#generateKeyPair().

The generated key pair or key will be returned by the generator and also stored in the Android Keystore under the alias specified in this spec. To obtain the secret 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, generated private keys implement java.security.interfaces.ECKey or java.security.interfaces.RSAKey interfaces whereas public keys implement java.security.interfaces.ECPublicKey or java.security.interfaces.RSAPublicKey interfaces.

For asymmetric key pairs, a X.509 certificate will be also generated and stored in the Android Keystore. This is because the java.security.KeyStore abstraction does not support storing key pairs without a certificate. The subject, serial number, and validity dates of the certificate can be customized in this spec. The certificate may be replaced at a later time by a certificate signed by a Certificate Authority (CA).

NOTE: If attestation is not requested using Builder#setAttestationChallenge(byte[]), generated certificate may be self-signed. If a private key is not authorized to sign the certificate, then the certificate will be created with an invalid signature which will not verify. Such a certificate is still useful because it provides access to the public key. To generate a valid signature for the certificate the key needs to be authorized for all of the following:

• KeyProperties#PURPOSE_SIGN,
• operation without requiring the user to be authenticated (see Builder#setUserAuthenticationRequired(boolean)),
• signing/origination at this moment in time (see Builder#setKeyValidityStart(Date) and Builder#setKeyValidityForOriginationEnd(Date)),
• suitable digest,
• (RSA keys only) padding scheme KeyProperties#SIGNATURE_PADDING_RSA_PKCS1.

NOTE: The key material of the generated symmetric and private keys is not accessible. The key material of the public keys is accessible.

Instances of this class are immutable.

Known issues

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

Example: NIST P-256 EC key pair for signing/verification using ECDSA

<code>KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
          KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
  keyPairGenerator.initialize(
          new KeyGenParameterSpec.Builder(
                  "key1",
                  KeyProperties.PURPOSE_SIGN)
                  .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
                  .setDigests(KeyProperties.DIGEST_SHA256,
                          KeyProperties.DIGEST_SHA384,
                          KeyProperties.DIGEST_SHA512)
                  // Only permit the private key to be used if the user authenticated
                  // within the last five minutes.
                  .setUserAuthenticationRequired(true)
                  .setUserAuthenticationValidityDurationSeconds(5 * 60)
                  .build());
  KeyPair keyPair = keyPairGenerator.generateKeyPair();
  Signature signature = Signature.getInstance("SHA256withECDSA");
  signature.initSign(keyPair.getPrivate());
  ...
 
  // The key pair can also be obtained from the Android Keystore any time as follows:
  KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
  keyStore.load(null);
  PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
  PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
  </code>

Example: RSA key pair for signing/verification using RSA-PSS

<code>KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
          KeyProperties.KEY_ALGORITHM_RSA, "AndroidKeyStore");
  keyPairGenerator.initialize(
          new KeyGenParameterSpec.Builder(
                  "key1",
                  KeyProperties.PURPOSE_SIGN)
                  .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
                  .setSignaturePaddings(KeyProperties.SIGNATURE_PADDING_RSA_PSS)
                  .build());
  KeyPair keyPair = keyPairGenerator.generateKeyPair();
  Signature signature = Signature.getInstance("SHA256withRSA/PSS");
  signature.initSign(keyPair.getPrivate());
  ...
 
  // The key pair can also be obtained from the Android Keystore any time as follows:
  KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
  keyStore.load(null);
  PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
  PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
  </code>

Example: RSA key pair for encryption/decryption using RSA OAEP

<code>KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
          KeyProperties.KEY_ALGORITHM_RSA, "AndroidKeyStore");
  keyPairGenerator.initialize(
          new KeyGenParameterSpec.Builder(
                  "key1",
                  KeyProperties.PURPOSE_DECRYPT)
                  .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
                  .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_OAEP)
                  .build());
  KeyPair keyPair = keyPairGenerator.generateKeyPair();
  Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
  cipher.init(Cipher.DECRYPT_MODE, keyPair.getPrivate());
  ...
 
  // The key pair can also be obtained from the Android Keystore any time as follows:
  KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
  keyStore.load(null);
  PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
  PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
  </code>

Example: AES key for encryption/decryption in GCM mode

<code>KeyGenerator keyGenerator = KeyGenerator.getInstance(
          KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore");
  keyGenerator.init(
          new KeyGenParameterSpec.Builder("key2",
                  KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
                  .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
                  .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
                  .build());
  SecretKey key = keyGenerator.generateKey();
 
  Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
  cipher.init(Cipher.ENCRYPT_MODE, key);
  ...
 
  // The key can also be obtained from the Android Keystore any time as follows:
  KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
  keyStore.load(null);
  key = (SecretKey) keyStore.getKey("key2", null);
  </code>

Example: HMAC key for generating a MAC using SHA-256

<code>KeyGenerator keyGenerator = KeyGenerator.getInstance(
          KeyProperties.KEY_ALGORITHM_HMAC_SHA256, "AndroidKeyStore");
  keyGenerator.init(
          new KeyGenParameterSpec.Builder("key2", KeyProperties.PURPOSE_SIGN).build());
  SecretKey key = keyGenerator.generateKey();
  Mac mac = Mac.getInstance("HmacSHA256");
  mac.init(key);
  ...
 
  // The key can also be obtained from the Android Keystore any time as follows:
  KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
  keyStore.load(null);
  key = (SecretKey) keyStore.getKey("key2", null);
  </code>

Example: EC key for ECDH key agreement

<code>KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
          KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
  keyPairGenerator.initialize(
          new KeyGenParameterSpec.Builder(
              "eckeypair",
              KeyProperties.PURPOSE_AGREE_KEY)
              .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
              .build());
  KeyPair myKeyPair = keyPairGenerator.generateKeyPair();
 
  // Exchange public keys with server. A new ephemeral key MUST be used for every message.
  PublicKey serverEphemeralPublicKey; // Ephemeral key received from server.
 
  // Create a shared secret based on our private key and the other party's public key.
  KeyAgreement keyAgreement = KeyAgreement.getInstance("ECDH", "AndroidKeyStore");
  keyAgreement.init(myKeyPair.getPrivate());
  keyAgreement.doPhase(serverEphemeralPublicKey, true);
  byte[] sharedSecret = keyAgreement.generateSecret();
 
  // sharedSecret cannot safely be used as a key yet. We must run it through a key derivation
  // function with some other data: "salt" and "info". Salt is an optional random value,
  // omitted in this example. It's good practice to include both public keys and any other
  // key negotiation data in info. Here we use the public keys and a label that indicates
  // messages encrypted with this key are coming from the server.
  byte[] salt = {};
  ByteArrayOutputStream info = new ByteArrayOutputStream();
  info.write("ECDH secp256r1 AES-256-GCM-SIV\0".getBytes(StandardCharsets.UTF_8));
  info.write(myKeyPair.getPublic().getEncoded());
  info.write(serverEphemeralPublicKey.getEncoded());
 
  // This example uses the Tink library and the HKDF key derivation function.
  AesGcmSiv key = new AesGcmSiv(Hkdf.computeHkdf(
          "HMACSHA256", sharedSecret, salt, info.toByteArray(), 32));
  byte[] associatedData = {};
  return key.decrypt(ciphertext, associatedData);
  </code>

Summary

Public methods

fun getAlgorithmParameterSpec(): AlgorithmParameterSpec?

fun getAttestKeyAlias(): String?

fun getAttestationChallenge(): ByteArray!

fun getBlockModes(): Array<String!>

fun getCertificateNotAfter(): Date

fun getCertificateNotBefore(): Date

fun getCertificateSerialNumber(): BigInteger

fun getCertificateSubject(): X500Principal

fun getDigests(): Array<String!>

fun getEncryptionPaddings(): Array<String!>

fun getKeySize(): Int

fun getKeyValidityForConsumptionEnd(): Date?

fun getKeyValidityForOriginationEnd(): Date?

fun getKeyValidityStart(): Date?

fun getKeystoreAlias(): String

fun getMaxUsageCount(): Int

fun getMgf1Digests(): MutableSet<String!>

fun getPurposes(): Int

fun getSignaturePaddings(): Array<String!>

fun getUserAuthenticationType(): Int

fun getUserAuthenticationValidityDurationSeconds(): Int

fun isDevicePropertiesAttestationIncluded(): Boolean

fun isDigestsSpecified(): Boolean

fun isInvalidatedByBiometricEnrollment(): Boolean

fun isMgf1DigestsSpecified(): Boolean

fun isRandomizedEncryptionRequired(): Boolean

fun isStrongBoxBacked(): Boolean

fun isUnlockedDeviceRequired(): Boolean

fun isUserAuthenticationRequired(): Boolean

fun isUserAuthenticationValidWhileOnBody(): Boolean

fun isUserConfirmationRequired(): Boolean

fun isUserPresenceRequired(): Boolean