Skip to content

Most visited

Recently visited

navigation

KeyGenParameterSpec.Builder

public static final class KeyGenParameterSpec.Builder
extends Object

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


Builder of KeyGenParameterSpec instances.

Summary

Public constructors

KeyGenParameterSpec.Builder(String keystoreAlias, int purposes)

Creates a new instance of the Builder.

Public methods

KeyGenParameterSpec build()

Builds an instance of KeyGenParameterSpec.

KeyGenParameterSpec.Builder setAlgorithmParameterSpec(AlgorithmParameterSpec spec)

Sets the algorithm-specific key generation parameters.

KeyGenParameterSpec.Builder setAttestationChallenge(byte[] attestationChallenge)

Sets whether an attestation certificate will be generated for this key pair, and what challenge value will be placed in the certificate.

KeyGenParameterSpec.Builder setBlockModes(String... blockModes)

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

KeyGenParameterSpec.Builder setCertificateNotAfter(Date date)

Sets the end of the validity period for the self-signed certificate of the generated key pair.

KeyGenParameterSpec.Builder setCertificateNotBefore(Date date)

Sets the start of the validity period for the self-signed certificate of the generated key pair.

KeyGenParameterSpec.Builder setCertificateSerialNumber(BigInteger serialNumber)

Sets the serial number used for the self-signed certificate of the generated key pair.

KeyGenParameterSpec.Builder setCertificateSubject(X500Principal subject)

Sets the subject used for the self-signed certificate of the generated key pair.

KeyGenParameterSpec.Builder setDigests(String... digests)

Sets the set of digests algorithms (e.g., SHA-256, SHA-384) with which the key can be used.

KeyGenParameterSpec.Builder setEncryptionPaddings(String... paddings)

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

KeyGenParameterSpec.Builder setInvalidatedByBiometricEnrollment(boolean invalidateKey)

Sets whether this key should be invalidated on fingerprint enrollment.

KeyGenParameterSpec.Builder setKeySize(int keySize)

Sets the size (in bits) of the key to be generated.

KeyGenParameterSpec.Builder setKeyValidityEnd(Date endDate)

Sets the time instant after which the key is no longer valid.

KeyGenParameterSpec.Builder setKeyValidityForConsumptionEnd(Date endDate)

Sets the time instant after which the key is no longer valid for decryption and verification.

KeyGenParameterSpec.Builder setKeyValidityForOriginationEnd(Date endDate)

Sets the time instant after which the key is no longer valid for encryption and signing.

KeyGenParameterSpec.Builder setKeyValidityStart(Date startDate)

Sets the time instant before which the key is not yet valid.

KeyGenParameterSpec.Builder setRandomizedEncryptionRequired(boolean required)

Sets whether encryption using this key must be sufficiently randomized to produce different ciphertexts for the same plaintext every time.

KeyGenParameterSpec.Builder setSignaturePaddings(String... paddings)

Sets the set of padding schemes (e.g., PSS, PKCS#1) with which the key can be used when signing/verifying.

KeyGenParameterSpec.Builder setUserAuthenticationRequired(boolean required)

Sets whether this key is authorized to be used only if the user has been authenticated.

KeyGenParameterSpec.Builder setUserAuthenticationValidWhileOnBody(boolean remainsValid)

Sets whether the key will remain authorized only until the device is removed from the user's body up to the limit of the authentication validity period (see setUserAuthenticationValidityDurationSeconds(int) and setUserAuthenticationRequired(boolean)).

KeyGenParameterSpec.Builder setUserAuthenticationValidityDurationSeconds(int seconds)

Sets the duration of time (seconds) for which this key is authorized to be used after the user is successfully authenticated.

Inherited methods

From class java.lang.Object

Public constructors

KeyGenParameterSpec.Builder

added in API level 23
KeyGenParameterSpec.Builder (String keystoreAlias, 
                int purposes)

Creates a new instance of the Builder.

Parameters
keystoreAlias String: alias of the entry in which the generated key will appear in Android KeyStore. Must not be empty.

This value must never be null.

purposes int: 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.

If the set of purposes for which the key can be used does not contain PURPOSE_SIGN, the self-signed certificate generated by KeyPairGenerator of AndroidKeyStore provider will contain an invalid signature. This is OK if the certificate is only used for obtaining the public key from Android KeyStore.

See KeyProperties.PURPOSE flags.

Public methods

build

added in API level 23
KeyGenParameterSpec build ()

Builds an instance of KeyGenParameterSpec.

Returns
KeyGenParameterSpec

This value will never be null.

setAlgorithmParameterSpec

added in API level 23
KeyGenParameterSpec.Builder setAlgorithmParameterSpec (AlgorithmParameterSpec spec)

Sets the algorithm-specific key generation parameters. For example, for RSA keys this may be an instance of RSAKeyGenParameterSpec whereas for EC keys this may be an instance of ECGenParameterSpec.

These key generation parameters must match other explicitly set parameters (if any), such as key size.

Parameters
spec AlgorithmParameterSpec

This value must never be null.

Returns
KeyGenParameterSpec.Builder

setAttestationChallenge

added in API level 24
KeyGenParameterSpec.Builder setAttestationChallenge (byte[] attestationChallenge)

Sets whether an attestation certificate will be generated for this key pair, and what challenge value will be placed in the certificate. The attestation certificate chain can be retrieved with with getCertificateChain(String).

If attestationChallenge is not 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 attestationChallenge 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.

The purpose of the challenge value is to enable relying parties to verify that the key was created in response to a specific request. If attestation is desired but no challenged is needed, any non-null value may be used, including an empty byte array.

If attestationChallenge is null, and this spec is used to generate an asymmetric (RSA or EC) key pair, the public key certificate will be self-signed if the key has purpose PURPOSE_SIGN. If the key does not have purpose PURPOSE_SIGN, it is not possible to use the key to sign a certificate, so the public key certificate will contain a dummy signature.

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

Parameters
attestationChallenge byte

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setBlockModes

added in API level 23
KeyGenParameterSpec.Builder setBlockModes (String... blockModes)

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

This must be specified for symmetric encryption/decryption keys.

See KeyProperties.BLOCK_MODE constants.

Parameters
blockModes String

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setCertificateNotAfter

added in API level 23
KeyGenParameterSpec.Builder setCertificateNotAfter (Date date)

Sets the end of the validity period for the self-signed certificate of the generated key pair.

By default, this date is Jan 1 2048.

Parameters
date Date

This value must never be null.

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setCertificateNotBefore

added in API level 23
KeyGenParameterSpec.Builder setCertificateNotBefore (Date date)

Sets the start of the validity period for the self-signed certificate of the generated key pair.

By default, this date is Jan 1 1970.

Parameters
date Date

This value must never be null.

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setCertificateSerialNumber

added in API level 23
KeyGenParameterSpec.Builder setCertificateSerialNumber (BigInteger serialNumber)

Sets the serial number used for the self-signed certificate of the generated key pair.

By default, the serial number is 1.

Parameters
serialNumber BigInteger

This value must never be null.

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setCertificateSubject

added in API level 23
KeyGenParameterSpec.Builder setCertificateSubject (X500Principal subject)

Sets the subject used for the self-signed certificate of the generated key pair.

By default, the subject is CN=fake.

Parameters
subject X500Principal

This value must never be null.

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setDigests

added in API level 23
KeyGenParameterSpec.Builder setDigests (String... digests)

Sets the set of digests algorithms (e.g., SHA-256, SHA-384) with which the key can be used. Attempts to use the key with any other digest algorithm will be rejected.

This must be specified for signing/verification keys and RSA encryption/decryption keys used with RSA OAEP padding scheme because these operations involve a digest. For HMAC keys, the default is the digest associated with the key algorithm (e.g., SHA-256 for key algorithm HmacSHA256). HMAC keys cannot be authorized for more than one digest.

For private keys used for TLS/SSL client or server authentication it is usually necessary to authorize the use of no digest (DIGEST_NONE). This is because TLS/SSL stacks typically generate the necessary digest(s) themselves and then use a private key to sign it.

See KeyProperties.DIGEST constants.

Parameters
digests String

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setEncryptionPaddings

added in API level 23
KeyGenParameterSpec.Builder setEncryptionPaddings (String... paddings)

Sets the set of padding schemes (e.g., PKCS7Padding, OAEPPadding, 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.

This must be specified for keys which are used for encryption/decryption.

For RSA private keys used by TLS/SSL servers to authenticate themselves to clients it is usually necessary to authorize the use of no/any padding (ENCRYPTION_PADDING_NONE) and/or PKCS#1 encryption padding (ENCRYPTION_PADDING_RSA_PKCS1). This is because RSA decryption is required by some cipher suites, and some stacks request decryption using no padding whereas others request PKCS#1 padding.

See KeyProperties.ENCRYPTION_PADDING constants.

Parameters
paddings String

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setInvalidatedByBiometricEnrollment

added in API level 24
KeyGenParameterSpec.Builder setInvalidatedByBiometricEnrollment (boolean invalidateKey)

Sets whether this key should be invalidated on fingerprint enrollment. This applies only to keys which require user authentication (see setUserAuthenticationRequired(boolean)) and if no positive validity duration has been set (see setUserAuthenticationValidityDurationSeconds(int), meaning the key is valid for fingerprint authentication only.

By default, invalidateKey is true, so keys that are valid for fingerprint authentication only are irreversibly invalidated when a new fingerprint is enrolled, or when all existing fingerprints are deleted. That may be changed by calling this method with invalidateKey set to false.

Invalidating keys on enrollment of a new finger or unenrollment of all fingers improves security by ensuring that an unauthorized person who obtains the password can't gain the use of fingerprint-authenticated keys by enrolling their own finger. However, invalidating keys makes key-dependent operations impossible, requiring some fallback procedure to authenticate the user and set up a new key.

Parameters
invalidateKey boolean

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setKeySize

added in API level 23
KeyGenParameterSpec.Builder setKeySize (int keySize)

Sets the size (in bits) of the key to be generated. For instance, for RSA keys this sets the modulus size, for EC keys this selects a curve with a matching field size, and for symmetric keys this sets the size of the bitstring which is their key material.

The default key size is specific to each key algorithm. If key size is not set via this method, it should be looked up from the algorithm-specific parameters (if any) provided via setAlgorithmParameterSpec.

Parameters
keySize int

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setKeyValidityEnd

added in API level 23
KeyGenParameterSpec.Builder setKeyValidityEnd (Date endDate)

Sets the time instant after which the key is no longer valid.

By default, the key is valid at any instant.

Parameters
endDate Date

Returns
KeyGenParameterSpec.Builder

This value will never be null.

See also:

setKeyValidityForConsumptionEnd

added in API level 23
KeyGenParameterSpec.Builder setKeyValidityForConsumptionEnd (Date endDate)

Sets the time instant after which the key is no longer valid for decryption and verification.

By default, the key is valid at any instant.

Parameters
endDate Date

Returns
KeyGenParameterSpec.Builder

This value will never be null.

See also:

setKeyValidityForOriginationEnd

added in API level 23
KeyGenParameterSpec.Builder setKeyValidityForOriginationEnd (Date endDate)

Sets the time instant after which the key is no longer valid for encryption and signing.

By default, the key is valid at any instant.

Parameters
endDate Date

Returns
KeyGenParameterSpec.Builder

This value will never be null.

See also:

setKeyValidityStart

added in API level 23
KeyGenParameterSpec.Builder setKeyValidityStart (Date startDate)

Sets the time instant before which the key is not yet valid.

By default, the key is valid at any instant.

Parameters
startDate Date

Returns
KeyGenParameterSpec.Builder

This value will never be null.

See also:

setRandomizedEncryptionRequired

added in API level 23
KeyGenParameterSpec.Builder setRandomizedEncryptionRequired (boolean required)

Sets whether 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.

By default, IND-CPA is required.

When IND-CPA is required:

  • encryption/decryption transformation which do not offer IND-CPA, such as ECB with a symmetric encryption algorithm, or RSA encryption/decryption without padding, are prohibited;
  • in block modes which use an IV, such as GCM, CBC, and CTR, caller-provided IVs are rejected when encrypting, to ensure that only random IVs are used.

Before disabling this requirement, consider the following approaches instead:

  • If you are generating a random IV for encryption and then initializing a Cipher using the IV, the solution is to let the Cipher generate a random IV instead. This will occur if the Cipher is initialized for encryption without an IV. The IV can then be queried via getIV().
  • If you are generating a non-random IV (e.g., an IV derived from something not fully random, such as the name of the file being encrypted, or transaction ID, or password, or a device identifier), consider changing your design to use a random IV which will then be provided in addition to the ciphertext to the entities which need to decrypt the ciphertext.
  • If you are using RSA encryption without padding, consider switching to encryption padding schemes which offer IND-CPA, such as PKCS#1 or OAEP.

Parameters
required boolean

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setSignaturePaddings

added in API level 23
KeyGenParameterSpec.Builder setSignaturePaddings (String... paddings)

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

This must be specified for RSA keys which are used for signing/verification.

See KeyProperties.SIGNATURE_PADDING constants.

Parameters
paddings String

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setUserAuthenticationRequired

added in API level 23
KeyGenParameterSpec.Builder setUserAuthenticationRequired (boolean required)

Sets whether this key is authorized to be used only if the user has been authenticated.

By default, the key is authorized to be used regardless of whether the user has been authenticated.

When user authentication is required:

  • The key can only be generated if secure lock screen is set up (see isDeviceSecure()). Additionally, if the key requires that user authentication takes place for every use of the key (see setUserAuthenticationValidityDurationSeconds(int)), at least one fingerprint must be enrolled (see hasEnrolledFingerprints()).
  • The use of the key must be authorized by the user by authenticating to this Android device using a subset of their secure lock screen credentials such as password/PIN/pattern or fingerprint. More information.
  • The key will become irreversibly invalidated once the secure lock screen is disabled (reconfigured to None, Swipe or other mode which does not authenticate the user) or when the secure lock screen is forcibly reset (e.g., by a Device Administrator). Additionally, if the key requires that user authentication takes place for every use of the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\ no more fingerprints are enrolled, unless setInvalidatedByBiometricEnrollment(boolean) is used to allow validity after enrollment. Attempts to initialize cryptographic operations using such keys will throw KeyPermanentlyInvalidatedException.

This authorization applies only to secret key and private key operations. Public key operations are not restricted.

Parameters
required boolean

Returns
KeyGenParameterSpec.Builder

This value will never be null.

See also:

setUserAuthenticationValidWhileOnBody

added in API level 24
KeyGenParameterSpec.Builder setUserAuthenticationValidWhileOnBody (boolean remainsValid)

Sets whether the key will remain authorized only until the device is removed from the user's body up to the limit of the authentication validity period (see setUserAuthenticationValidityDurationSeconds(int) and setUserAuthenticationRequired(boolean)). Once the device has been removed from the user's body, the key will be considered unauthorized and the user will need to re-authenticate to use it. For keys without an authentication validity period this parameter has no effect.

Similarly, on devices that do not have an on-body sensor, this parameter will have no effect; the device will always be considered to be "on-body" and the key will therefore remain authorized until the validity period ends.

Parameters
remainsValid boolean: if true, and if the device supports on-body detection, key will be invalidated when the device is removed from the user's body or when the authentication validity expires, whichever occurs first.

Returns
KeyGenParameterSpec.Builder

This value will never be null.

setUserAuthenticationValidityDurationSeconds

added in API level 23
KeyGenParameterSpec.Builder setUserAuthenticationValidityDurationSeconds (int seconds)

Sets the duration of time (seconds) for which this key is authorized to be used after the user is successfully authenticated. This has effect if the key requires user authentication for its use (see setUserAuthenticationRequired(boolean)).

By default, if user authentication is required, it must take place for every use of the key.

Cryptographic operations involving keys which require user authentication to take place for every operation can only use fingerprint authentication. This is achieved by initializing a cryptographic operation (Signature, Cipher, Mac) with the key, wrapping it into a FingerprintManager.CryptoObject, invoking FingerprintManager.authenticate with CryptoObject, and proceeding with the cryptographic operation only if the authentication flow succeeds.

Cryptographic operations involving keys which are authorized to be used for a duration of time after a successful user authentication event can only use secure lock screen authentication. These cryptographic operations will throw UserNotAuthenticatedException during initialization if the user needs to be authenticated to proceed. This situation can be resolved by the user unlocking the secure lock screen of the Android or by going through the confirm credential flow initiated by createConfirmDeviceCredentialIntent(CharSequence, CharSequence). Once resolved, initializing a new cryptographic operation using this key (or any other key which is authorized to be used for a fixed duration of time after user authentication) should succeed provided the user authentication flow completed successfully.

Parameters
seconds int: duration in seconds or -1 if user authentication must take place for every use of the key.

Value is -1 or greater.

Returns
KeyGenParameterSpec.Builder

This value will never be null.

See also:

This site uses cookies to store your preferences for site-specific language and display options.

Get the latest Android developer news and tips that will help you find success on Google Play.

* Required Fields

Hooray!

Browse this site in ?

You requested a page in , but your language preference for this site is .

Would you like to change your language preference and browse this site in ? If you want to change your language preference later, use the language menu at the bottom of each page.

This class requires API level or higher

This doc is hidden because your selected API level for the documentation is . You can change the documentation API level with the selector above the left navigation.

For more information about specifying the API level your app requires, read Supporting Different Platform Versions.

Take a short survey?
Help us improve the Android developer experience.
(Sep 2017 survey)