Most visited

Recently visited

Added in API level 23

KeyGenParameterSpec

public final class KeyGenParameterSpec
extends Object implements AlgorithmParameterSpec

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


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 KeyGenParameterSpec.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 generateKey() or 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 getCertificate(String) and then getPublicKey().

To help obtain algorithm-specific public parameters of key pairs stored in the Android Keystore, generated private keys implement ECKey or RSAKey interfaces whereas public keys implement ECPublicKey or RSAPublicKey interfaces.

For asymmetric key pairs, a self-signed X.509 certificate will be also generated and stored in the Android Keystore. This is because the 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 self-signed certificate may be replaced at a later time by a certificate signed by a Certificate Authority (CA).

NOTE: If a private key is not authorized to sign the self-signed 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:

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

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: NIST P-256 EC key pair for signing/verification using ECDSA

This example illustrates how to generate a NIST P-256 (aka secp256r1 aka prime256v1) EC key pair in the Android KeyStore system under alias key1 where the private key is authorized to be used only for signing using SHA-256, SHA-384, or SHA-512 digest and only if the user has been authenticated within the last five minutes. The use of the public key is unrestricted (See Known Issues).
 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();
 

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

This example illustrates how to generate an RSA key pair in the Android KeyStore system under alias key1 authorized to be used only for signing using the RSA-PSS signature padding scheme with SHA-256 or SHA-512 digests. The use of the public key is unrestricted.
 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();
 

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

This example illustrates how to generate an RSA key pair in the Android KeyStore system under alias key1 where the private key is authorized to be used only for decryption using RSA OAEP encryption padding scheme with SHA-256 or SHA-512 digests. The use of the public key is unrestricted.
 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();
 

Example: AES key for encryption/decryption in GCM mode

The following example illustrates how to generate an AES key in the Android KeyStore system under alias key2 authorized to be used only for encryption/decryption in GCM mode with no padding.
 KeyGenerator keyGenerator = KeyGenerator.getInstance(
         KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore");
 keyGenerator.initialize(
         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);
 

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

This example illustrates how to generate an HMAC key in the Android KeyStore system under alias key2 authorized to be used only for generating an HMAC using SHA-256.
 KeyGenerator keyGenerator = KeyGenerator.getInstance(
         KeyProperties.KEY_ALGORITHM_HMAC_SHA256, "AndroidKeyStore");
 keyGenerator.initialize(
         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);
 

Summary

Nested classes

class KeyGenParameterSpec.Builder

Builder of KeyGenParameterSpec instances. 

Public methods

AlgorithmParameterSpec getAlgorithmParameterSpec()

Returns the key algorithm-specific AlgorithmParameterSpec that will be used for creation of the key or null if algorithm-specific defaults should be used.

byte[] getAttestationChallenge()

Returns the attestation challenge value that will be placed in attestation certificate for this key pair.

String[] getBlockModes()

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

Date getCertificateNotAfter()

Returns the end date to be used on the X.509 certificate that will be put in the KeyStore.

Date getCertificateNotBefore()

Returns the start date to be used on the X.509 certificate that will be put in the KeyStore.

BigInteger getCertificateSerialNumber()

Returns the serial number to be used on the X.509 certificate that will be put in the KeyStore.

X500Principal getCertificateSubject()

Returns the subject distinguished name to be used on the X.509 certificate that will be put in the KeyStore.

String[] getDigests()

Returns the set of digest algorithms (e.g., SHA-256, SHA-384 with which the key can be used or null if not specified.

String[] getEncryptionPaddings()

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

int getKeySize()

Returns the requested key size.

Date getKeyValidityForConsumptionEnd()

Returns the time instant after which the key is no longer valid for decryption and verification or null if not restricted.

Date getKeyValidityForOriginationEnd()

Returns the time instant after which the key is no longer valid for encryption and signing or null if not restricted.

Date getKeyValidityStart()

Returns the time instant before which the key is not yet valid or null if not restricted.

String getKeystoreAlias()

Returns the alias that will be used in the java.security.KeyStore in conjunction with the AndroidKeyStore.

int getPurposes()

Returns 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 remain authorized only until the device is removed from the user's body, up to the validity duration.

Inherited methods

From class java.lang.Object

Public methods

getAlgorithmParameterSpec

Added in API level 23
AlgorithmParameterSpec getAlgorithmParameterSpec ()

Returns the key algorithm-specific AlgorithmParameterSpec that will be used for creation of the key or null if algorithm-specific defaults should be used.

Returns
AlgorithmParameterSpec

getAttestationChallenge

Added in API level 24
byte[] getAttestationChallenge ()

Returns the attestation challenge value that will be placed in attestation certificate for this key pair.

If this method returns non-null, the public key certificate for this key pair will contain an extension that describes the details of the key's configuration and authorizations, including the content of the attestation challenge value. If the key is in secure hardware, and if the secure hardware supports attestation, the certificate will be signed by a chain of certificates rooted at a trustworthy CA key. Otherwise the chain will be rooted at an untrusted certificate.

If this method returns null, and the spec is used to generate an asymmetric (RSA or EC) key pair, the public key will have a self-signed certificate if it has purpose PURPOSE_SIGN. If does not have purpose PURPOSE_SIGN, it will have a fake certificate.

Symmetric keys, such as AES and HMAC keys, do not have public key certificates. If a KeyGenParameterSpec with getAttestationChallenge returning non-null is used to generate a symmetric (AES or HMAC) key, generateKey() will throw InvalidAlgorithmParameterException.

Returns
byte[]

See also:

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

getCertificateNotAfter

Added in API level 23
Date getCertificateNotAfter ()

Returns the end date to be used on the X.509 certificate that will be put in the KeyStore.

Returns
Date

getCertificateNotBefore

Added in API level 23
Date getCertificateNotBefore ()

Returns the start date to be used on the X.509 certificate that will be put in the KeyStore.

Returns
Date

getCertificateSerialNumber

Added in API level 23
BigInteger getCertificateSerialNumber ()

Returns the serial number to be used on the X.509 certificate that will be put in the KeyStore.

Returns
BigInteger

getCertificateSubject

Added in API level 23
X500Principal getCertificateSubject ()

Returns the subject distinguished name to be used on the X.509 certificate that will be put in the KeyStore.

Returns
X500Principal

getDigests

Added in API level 23
String[] getDigests ()

Returns the set of digest algorithms (e.g., SHA-256, SHA-384 with which the key can be used or null if not specified.

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

Returns the set of padding schemes (e.g., PKCS7Padding, OEAPPadding, 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[]

getKeySize

Added in API level 23
int getKeySize ()

Returns the requested key size. If -1, the size should be looked up from getAlgorithmParameterSpec(), if provided, otherwise an algorithm-specific default size should be used.

Returns
int

getKeyValidityForConsumptionEnd

Added in API level 23
Date getKeyValidityForConsumptionEnd ()

Returns the time instant after which the key is no longer valid for decryption and verification or null if not restricted.

Returns
Date

getKeyValidityForOriginationEnd

Added in API level 23
Date getKeyValidityForOriginationEnd ()

Returns the time instant after which the key is no longer valid for encryption and signing or null if not restricted.

Returns
Date

getKeyValidityStart

Added in API level 23
Date getKeyValidityStart ()

Returns the time instant before which the key is not yet valid or null if not restricted.

Returns
Date

getKeystoreAlias

Added in API level 23
String getKeystoreAlias ()

Returns the alias that will be used in the java.security.KeyStore in conjunction with the AndroidKeyStore.

Returns
String

getPurposes

Added in API level 23
int getPurposes ()

Returns 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 remain authorized only until the device is removed from the user's body, up to the validity duration. 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:

Hooray!