# KeyGenParameterSpec.Builder
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
Summary:[Ctors](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#pubctors)\|[Methods](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#pubmethods)\|[Inherited Methods](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#inhmethods)
# KeyGenParameterSpec.Builder
*** ** * ** ***
[Kotlin](https://developer.android.com/reference/kotlin/android/security/keystore/KeyGenParameterSpec.Builder "View this page in Kotlin")\|Java
`
public
static
final
class
KeyGenParameterSpec.Builder
`
`
extends `[Object](https://developer.android.com/reference/java/lang/Object)`
``
`
|---|-------------------------------------------------------|
| [java.lang.Object](https://developer.android.com/reference/java/lang/Object) ||
| ↳ | android.security.keystore.KeyGenParameterSpec.Builder |
*** ** * ** ***
Builder of[KeyGenParameterSpec](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec)instances.
## Summary
| ### Public constructors ||
|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
| ` `[Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#Builder(java.lang.String,%20int))`(`[String](https://developer.android.com/reference/java/lang/String)` keystoreAlias, int purposes) ` Creates a new instance of the`Builder`. |
| ### Public methods ||
|---------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| ` `[KeyGenParameterSpec](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec) | ` `[build](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#build())`() ` Builds an instance of`KeyGenParameterSpec`. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setAlgorithmParameterSpec](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setAlgorithmParameterSpec(java.security.spec.AlgorithmParameterSpec))`(`[AlgorithmParameterSpec](https://developer.android.com/reference/java/security/spec/AlgorithmParameterSpec)` spec) ` Sets the algorithm-specific key generation parameters. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setAttestKeyAlias](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setAttestKeyAlias(java.lang.String))`(`[String](https://developer.android.com/reference/java/lang/String)` attestKeyAlias) ` Sets the alias of the attestation key that will be used to sign the attestation certificate for the generated key pair, if an attestation challenge is set with[setAttestationChallenge(byte)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setAttestationChallenge(byte[])). |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setAttestationChallenge](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setAttestationChallenge(byte[]))`(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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setBlockModes](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setBlockModes(java.lang.String[]))`(`[String...](https://developer.android.com/reference/java/lang/String)` blockModes) ` Sets the set of block modes (e.g.,`GCM`,`CBC`) with which the key can be used when encrypting/decrypting. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setCertificateNotAfter](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setCertificateNotAfter(java.util.Date))`(`[Date](https://developer.android.com/reference/java/util/Date)` date) ` Sets the end of the validity period for the certificate of the generated key pair. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setCertificateNotBefore](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setCertificateNotBefore(java.util.Date))`(`[Date](https://developer.android.com/reference/java/util/Date)` date) ` Sets the start of the validity period for the certificate of the generated key pair. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setCertificateSerialNumber](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setCertificateSerialNumber(java.math.BigInteger))`(`[BigInteger](https://developer.android.com/reference/java/math/BigInteger)` serialNumber) ` Sets the serial number used for the certificate of the generated key pair. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setCertificateSubject](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setCertificateSubject(javax.security.auth.x500.X500Principal))`(`[X500Principal](https://developer.android.com/reference/javax/security/auth/x500/X500Principal)` subject) ` Sets the subject used for the certificate of the generated key pair. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setDevicePropertiesAttestationIncluded](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setDevicePropertiesAttestationIncluded(boolean))`(boolean devicePropertiesAttestationIncluded) ` Sets whether to include the base device properties in the attestation certificate. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setDigests](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setDigests(java.lang.String[]))`(`[String...](https://developer.android.com/reference/java/lang/String)` digests) ` Sets the set of digests algorithms (e.g.,`SHA-256`,`SHA-384`) with which the key can be used. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setEncryptionPaddings](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setEncryptionPaddings(java.lang.String[]))`(`[String...](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setInvalidatedByBiometricEnrollment](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setInvalidatedByBiometricEnrollment(boolean))`(boolean invalidateKey) ` Sets whether this key should be invalidated on biometric enrollment. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setIsStrongBoxBacked](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setIsStrongBoxBacked(boolean))`(boolean isStrongBoxBacked) ` Sets whether this key should be protected by a StrongBox security chip. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setKeySize](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeySize(int))`(int keySize) ` Sets the size (in bits) of the key to be generated. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setKeyValidityEnd](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityEnd(java.util.Date))`(`[Date](https://developer.android.com/reference/java/util/Date)` endDate) ` Sets the time instant after which the key is no longer valid. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setKeyValidityForConsumptionEnd](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityForConsumptionEnd(java.util.Date))`(`[Date](https://developer.android.com/reference/java/util/Date)` endDate) ` Sets the time instant after which the key is no longer valid for decryption and verification. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setKeyValidityForOriginationEnd](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityForOriginationEnd(java.util.Date))`(`[Date](https://developer.android.com/reference/java/util/Date)` endDate) ` Sets the time instant after which the key is no longer valid for encryption and signing. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setKeyValidityStart](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityStart(java.util.Date))`(`[Date](https://developer.android.com/reference/java/util/Date)` startDate) ` Sets the time instant before which the key is not yet valid. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setMaxUsageCount](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setMaxUsageCount(int))`(int maxUsageCount) ` Sets the maximum number of times the key is allowed to be used. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setMgf1Digests](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setMgf1Digests(java.lang.String[]))`(`[String...](https://developer.android.com/reference/java/lang/String)` mgf1Digests) ` Sets the set of hash functions (e.g.,`SHA-256`,`SHA-384`) which could be used by the mask generation function MGF1 (which is used for certain operations with the key). |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setRandomizedEncryptionRequired](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setRandomizedEncryptionRequired(boolean))`(boolean required) ` Sets whether encryption using this key must be sufficiently randomized to produce different ciphertexts for the same plaintext every time. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setSignaturePaddings](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setSignaturePaddings(java.lang.String[]))`(`[String...](https://developer.android.com/reference/java/lang/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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUnlockedDeviceRequired](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUnlockedDeviceRequired(boolean))`(boolean unlockedDeviceRequired) ` Sets whether this key is authorized to be used only while the device is unlocked. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUserAuthenticationParameters](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationParameters(int,%20int))`(int timeout, int type) ` Sets the duration of time (seconds) and authorization type for which this key is authorized to be used after the user is successfully authenticated. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUserAuthenticationRequired](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))`(boolean required) ` Sets whether this key is authorized to be used only if the user has been authenticated. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUserAuthenticationValidWhileOnBody](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidWhileOnBody(boolean))`(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)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidityDurationSeconds(int))and[setUserAuthenticationRequired(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))). |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUserAuthenticationValidityDurationSeconds](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidityDurationSeconds(int))`(int seconds) ` *This method was deprecated in API level 30. See[setUserAuthenticationParameters(int, int)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationParameters(int,%20int))* |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUserConfirmationRequired](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserConfirmationRequired(boolean))`(boolean required) ` Sets whether this key is authorized to be used only for messages confirmed by the user. |
| ` `[KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | ` `[setUserPresenceRequired](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserPresenceRequired(boolean))`(boolean required) ` Sets whether a test of user presence is required to be performed between the`Signature.initSign()`and`Signature.sign()`method calls. |
| ### Inherited methods |
|-----------------------|---|
| From class` `[java.lang.Object](https://developer.android.com/reference/java/lang/Object)` ` |--------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ` `[Object](https://developer.android.com/reference/java/lang/Object) | ` `[clone](https://developer.android.com/reference/java/lang/Object#clone())`() ` Creates and returns a copy of this object. | | ` boolean` | ` `[equals](https://developer.android.com/reference/java/lang/Object#equals(java.lang.Object))`(`[Object](https://developer.android.com/reference/java/lang/Object)` obj) ` Indicates whether some other object is "equal to" this one. | | ` void` | ` `[finalize](https://developer.android.com/reference/java/lang/Object#finalize())`() ` Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. | | ` final `[Class](https://developer.android.com/reference/java/lang/Class)`` | ` `[getClass](https://developer.android.com/reference/java/lang/Object#getClass())`() ` Returns the runtime class of this`Object`. | | ` int` | ` `[hashCode](https://developer.android.com/reference/java/lang/Object#hashCode())`() ` Returns a hash code value for the object. | | ` final void` | ` `[notify](https://developer.android.com/reference/java/lang/Object#notify())`() ` Wakes up a single thread that is waiting on this object's monitor. | | ` final void` | ` `[notifyAll](https://developer.android.com/reference/java/lang/Object#notifyAll())`() ` Wakes up all threads that are waiting on this object's monitor. | | ` `[String](https://developer.android.com/reference/java/lang/String) | ` `[toString](https://developer.android.com/reference/java/lang/Object#toString())`() ` Returns a string representation of the object. | | ` final void` | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long,%20int))`(long timeoutMillis, int nanos) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait(long))`(long timeoutMillis) ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*, or until a certain amount of real time has elapsed. | | ` final void` | ` `[wait](https://developer.android.com/reference/java/lang/Object#wait())`() ` Causes the current thread to wait until it is awakened, typically by being*notified* or*interrupted*. | ||
## Public constructors
### Builder
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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 cannot 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. See[KeyProperties](https://developer.android.com/reference/android/security/keystore/KeyProperties).`PURPOSE`flags. Value is either`0`or a combination of[KeyProperties.PURPOSE_ENCRYPT](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_ENCRYPT),[KeyProperties.PURPOSE_DECRYPT](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_DECRYPT),[KeyProperties.PURPOSE_SIGN](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_SIGN),[KeyProperties.PURPOSE_VERIFY](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_VERIFY),[KeyProperties.PURPOSE_WRAP_KEY](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_WRAP_KEY),[KeyProperties.PURPOSE_AGREE_KEY](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_AGREE_KEY), and[KeyProperties.PURPOSE_ATTEST_KEY](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_ATTEST_KEY) |
## Public methods
### build
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec build ()
```
Builds an instance of`KeyGenParameterSpec`.
| Returns ||
|--------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec) | This value cannot be`null`.
|
### setAlgorithmParameterSpec
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setAlgorithmParameterSpec (AlgorithmParameterSpec spec)
```
Sets the algorithm-specific key generation parameters. For example, for RSA keys this may be an instance of[RSAKeyGenParameterSpec](https://developer.android.com/reference/java/security/spec/RSAKeyGenParameterSpec)whereas for EC keys this may be an instance of[ECGenParameterSpec](https://developer.android.com/reference/java/security/spec/ECGenParameterSpec).
These key generation parameters must match other explicitly set parameters (if any), such as key size.
| Parameters ||
|--------|--------------------------------------------------------------|
| `spec` | `AlgorithmParameterSpec`: This value cannot be`null`.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|--------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) |
|
### setAttestKeyAlias
Added in[API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setAttestKeyAlias (String attestKeyAlias)
```
Sets the alias of the attestation key that will be used to sign the attestation certificate for the generated key pair, if an attestation challenge is set with[setAttestationChallenge(byte)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setAttestationChallenge(byte[])). If an attestKeyAlias is set but no challenge,[KeyPairGenerator.initialize(int)](https://developer.android.com/reference/java/security/KeyPairGenerator#initialize(int))will throw[InvalidAlgorithmParameterException](https://developer.android.com/reference/java/security/InvalidAlgorithmParameterException).
If the attestKeyAlias is set to null (the default), Android Keystore will select an appropriate system-provided attestation signing key. If not null, the alias must reference an Android Keystore Key that was created with[KeyProperties.PURPOSE_ATTEST_KEY](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_ATTEST_KEY), or key generation will throw[InvalidAlgorithmParameterException](https://developer.android.com/reference/java/security/InvalidAlgorithmParameterException).
| Parameters ||
|------------------|----------------------------------------------------------------------------------------------------------------------------|
| `attestKeyAlias` | `String`: the alias of the attestation key to be used to sign the attestation certificate. This value may be`null`.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|--------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) |
|
### setAttestationChallenge
Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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[KeyStore.getCertificateChain(String)](https://developer.android.com/reference/java/security/KeyStore#getCertificateChain(java.lang.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[KeyProperties.PURPOSE_SIGN](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_SIGN). If the key does not have purpose[KeyProperties.PURPOSE_SIGN](https://developer.android.com/reference/android/security/keystore/KeyProperties#PURPOSE_SIGN), it is not possible to use the key to sign a certificate, so the public key certificate will contain a placeholder signature.
Symmetric keys, such as AES and HMAC keys, do not have public key certificates. If a[KeyGenParameterSpec.getAttestationChallenge()](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec#getAttestationChallenge())returns non-null and the spec is used to generate a symmetric (AES or HMAC) key,[KeyGenerator.generateKey()](https://developer.android.com/reference/javax/crypto/KeyGenerator#generateKey())will throw[InvalidAlgorithmParameterException](https://developer.android.com/reference/java/security/InvalidAlgorithmParameterException).
The challenge may be up to 128 bytes.
| Parameters ||
|------------------------|---------------|
| `attestationChallenge` | `byte`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|--------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) |
|
### setBlockModes
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyProperties).`BLOCK_MODE`constants.
| Parameters ||
|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `blockModes` | `String`: Value is[KeyProperties.BLOCK_MODE_ECB](https://developer.android.com/reference/android/security/keystore/KeyProperties#BLOCK_MODE_ECB),[KeyProperties.BLOCK_MODE_CBC](https://developer.android.com/reference/android/security/keystore/KeyProperties#BLOCK_MODE_CBC),[KeyProperties.BLOCK_MODE_CTR](https://developer.android.com/reference/android/security/keystore/KeyProperties#BLOCK_MODE_CTR), or[KeyProperties.BLOCK_MODE_GCM](https://developer.android.com/reference/android/security/keystore/KeyProperties#BLOCK_MODE_GCM)
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setCertificateNotAfter
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setCertificateNotAfter (Date date)
```
Sets the end of the validity period for the certificate of the generated key pair.
By default, this date is`Jan 1 2048`.
| Parameters ||
|--------|--------------------------------------------|
| `date` | `Date`: This value cannot be`null`.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setCertificateNotBefore
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setCertificateNotBefore (Date date)
```
Sets the start of the validity period for the certificate of the generated key pair.
By default, this date is`Jan 1 1970`.
| Parameters ||
|--------|--------------------------------------------|
| `date` | `Date`: This value cannot be`null`.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setCertificateSerialNumber
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setCertificateSerialNumber (BigInteger serialNumber)
```
Sets the serial number used for the certificate of the generated key pair. To ensure compatibility with devices and certificate parsers, the value should be 20 bytes or shorter (see RFC 5280 section 4.1.2.2).
By default, the serial number is`1`.
| Parameters ||
|----------------|--------------------------------------------------|
| `serialNumber` | `BigInteger`: This value cannot be`null`.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setCertificateSubject
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setCertificateSubject (X500Principal subject)
```
Sets the subject used for the certificate of the generated key pair.
By default, the subject is`CN=fake`.
| Parameters ||
|-----------|-----------------------------------------------------|
| `subject` | `X500Principal`: This value cannot be`null`.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setDevicePropertiesAttestationIncluded
Added in[API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setDevicePropertiesAttestationIncluded (boolean devicePropertiesAttestationIncluded)
```
Sets whether to include the base device properties in the attestation certificate.
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 device properties values (brand, device, manufacturer, model, product). These should be the same as in ([Build.BRAND](https://developer.android.com/reference/android/os/Build#BRAND),[Build.DEVICE](https://developer.android.com/reference/android/os/Build#DEVICE),[Build.MANUFACTURER](https://developer.android.com/reference/android/os/Build#MANUFACTURER),[Build.MODEL](https://developer.android.com/reference/android/os/Build#MODEL),[Build.PRODUCT](https://developer.android.com/reference/android/os/Build#PRODUCT)). The attestation certificate chain can be retrieved with[KeyStore.getCertificateChain(String)](https://developer.android.com/reference/java/security/KeyStore#getCertificateChain(java.lang.String)).
If`attestationChallenge`is`null`, the public key certificate for this key pair will not contain the extension with the requested attested values.
[KeyGenerator.generateKey()](https://developer.android.com/reference/javax/crypto/KeyGenerator#generateKey())will throw[ProviderException](https://developer.android.com/reference/java/security/ProviderException)if device properties attestation fails or is not supported.
| Parameters ||
|---------------------------------------|------------------|
| `devicePropertiesAttestationIncluded` | `boolean`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|--------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) |
|
### setDigests
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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 ([KeyProperties.DIGEST_NONE](https://developer.android.com/reference/android/security/keystore/KeyProperties#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](https://developer.android.com/reference/android/security/keystore/KeyProperties).`DIGEST`constants.
| Parameters ||
|-----------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `digests` | `String`: Value is[KeyProperties.DIGEST_NONE](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_NONE),[KeyProperties.DIGEST_MD5](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_MD5),[KeyProperties.DIGEST_SHA1](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA1),[KeyProperties.DIGEST_SHA224](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA224),[KeyProperties.DIGEST_SHA256](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA256),[KeyProperties.DIGEST_SHA384](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA384), or[KeyProperties.DIGEST_SHA512](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA512)
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setEncryptionPaddings
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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 ([KeyProperties.ENCRYPTION_PADDING_NONE](https://developer.android.com/reference/android/security/keystore/KeyProperties#ENCRYPTION_PADDING_NONE)) and/or PKCS#1 encryption padding ([KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1](https://developer.android.com/reference/android/security/keystore/KeyProperties#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](https://developer.android.com/reference/android/security/keystore/KeyProperties).`ENCRYPTION_PADDING`constants.
| Parameters ||
|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `paddings` | `String`: Value is[KeyProperties.ENCRYPTION_PADDING_NONE](https://developer.android.com/reference/android/security/keystore/KeyProperties#ENCRYPTION_PADDING_NONE),[KeyProperties.ENCRYPTION_PADDING_PKCS7](https://developer.android.com/reference/android/security/keystore/KeyProperties#ENCRYPTION_PADDING_PKCS7),[KeyProperties.ENCRYPTION_PADDING_RSA_PKCS1](https://developer.android.com/reference/android/security/keystore/KeyProperties#ENCRYPTION_PADDING_RSA_PKCS1), or[KeyProperties.ENCRYPTION_PADDING_RSA_OAEP](https://developer.android.com/reference/android/security/keystore/KeyProperties#ENCRYPTION_PADDING_RSA_OAEP)
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setInvalidatedByBiometricEnrollment
Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setInvalidatedByBiometricEnrollment (boolean invalidateKey)
```
Sets whether this key should be invalidated on biometric enrollment. This applies only to keys which require user authentication (see[setUserAuthenticationRequired(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))) and if no positive validity duration has been set (see[setUserAuthenticationValidityDurationSeconds(int)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidityDurationSeconds(int)), meaning the key is valid for biometric authentication only.
By default,`invalidateKey`is`true`, so keys that are valid for biometric authentication only are*irreversibly invalidated* when a new biometric is enrolled, or when all existing biometrics are deleted. That may be changed by calling this method with`invalidateKey`set to`false`.
Invalidating keys on enrollment of a new biometric or unenrollment of all biometrics improves security by ensuring that an unauthorized person who obtains the password can't gain the use of biometric-authenticated keys by enrolling their own biometric. 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setIsStrongBoxBacked
Added in[API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setIsStrongBoxBacked (boolean isStrongBoxBacked)
```
Sets whether this key should be protected by a StrongBox security chip.
| Parameters ||
|---------------------|------------------|
| `isStrongBoxBacked` | `boolean`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setKeySize
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setAlgorithmParameterSpec(java.security.spec.AlgorithmParameterSpec)).
| Parameters ||
|-----------|--------------|
| `keySize` | `int`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setKeyValidityEnd
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setKeyValidityStart(Date)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityStart(java.util.Date))
- [setKeyValidityForConsumptionEnd(Date)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityForConsumptionEnd(java.util.Date))
- [setKeyValidityForOriginationEnd(Date)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityForOriginationEnd(java.util.Date))
### setKeyValidityForConsumptionEnd
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setKeyValidityForOriginationEnd(Date)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityForOriginationEnd(java.util.Date))
### setKeyValidityForOriginationEnd
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setKeyValidityForConsumptionEnd(Date)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityForConsumptionEnd(java.util.Date))
### setKeyValidityStart
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setKeyValidityEnd(Date)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setKeyValidityEnd(java.util.Date))
### setMaxUsageCount
Added in[API level 31](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setMaxUsageCount (int maxUsageCount)
```
Sets the maximum number of times the key is allowed to be used. After every use of the key, the use counter will decrease. This authorization applies only to secret key and private key operations. Public key operations are not restricted. For example, after successfully encrypting and decrypting data using methods such as[Cipher.doFinal()](https://developer.android.com/reference/javax/crypto/Cipher#doFinal()), the use counter of the secret key will decrease. After successfully signing data using methods such as[Signature.sign()](https://developer.android.com/reference/java/security/Signature#sign()), the use counter of the private key will decrease. When the use counter is depleted, the key will be marked for deletion by Android Keystore and any subsequent attempt to use the key will throw[KeyPermanentlyInvalidatedException](https://developer.android.com/reference/android/security/keystore/KeyPermanentlyInvalidatedException). There is no key to be loaded from the Android Keystore once the exhausted key is permanently deleted, as if the key never existed before.
By default, there is no restriction on the usage of key.
Some secure hardware may not support this feature at all, in which case it will be enforced in software, some secure hardware may support it but only with maxUsageCount = 1, and some secure hardware may support it with larger value of maxUsageCount.
The PackageManger feature flags:[PackageManager.FEATURE_KEYSTORE_SINGLE_USE_KEY](https://developer.android.com/reference/android/content/pm/PackageManager#FEATURE_KEYSTORE_SINGLE_USE_KEY)and[PackageManager.FEATURE_KEYSTORE_LIMITED_USE_KEY](https://developer.android.com/reference/android/content/pm/PackageManager#FEATURE_KEYSTORE_LIMITED_USE_KEY)can be used to check whether the secure hardware cannot enforce this feature, can only enforce it with maxUsageCount = 1, or can enforce it with larger value of maxUsageCount.
| Parameters ||
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `maxUsageCount` | `int`: maximum number of times the key is allowed to be used or[KeyProperties.UNRESTRICTED_USAGE_COUNT](https://developer.android.com/reference/android/security/keystore/KeyProperties#UNRESTRICTED_USAGE_COUNT)if there is no restriction on the usage.
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setMgf1Digests
Added in[API level 35](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setMgf1Digests (String... mgf1Digests)
```
Sets the set of hash functions (e.g.,`SHA-256`,`SHA-384`) which could be used by the mask generation function MGF1 (which is used for certain operations with the key). Attempts to use the key with any other digest for the mask generation function will be rejected.
This can only be specified for signing/verification keys and RSA encryption/decryption keys used with RSA OAEP padding scheme because these operations involve a mask generation function (MGF1) with a digest. The default digest for MGF1 is`SHA-1`, which will be specified during key creation time if no digests have been explicitly provided.`null`may not be specified as a parameter to this method: It is not possible to disable MGF1 digest, a default must be present for when the caller tries to use it.
When using the key, the caller may not specify any digests that were not provided during key creation time. The caller may specify the default digest,`SHA-1`, if no digests were explicitly provided during key creation (but it is not necessary to do so).
See[KeyProperties](https://developer.android.com/reference/android/security/keystore/KeyProperties).`DIGEST`constants.
| Parameters ||
|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `mgf1Digests` | `String`: This value cannot be`null`. Value is[KeyProperties.DIGEST_NONE](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_NONE),[KeyProperties.DIGEST_MD5](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_MD5),[KeyProperties.DIGEST_SHA1](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA1),[KeyProperties.DIGEST_SHA224](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA224),[KeyProperties.DIGEST_SHA256](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA256),[KeyProperties.DIGEST_SHA384](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA384), or[KeyProperties.DIGEST_SHA512](https://developer.android.com/reference/android/security/keystore/KeyProperties#DIGEST_SHA512)
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|--------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) |
|
### setRandomizedEncryptionRequired
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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 aCipher 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[Cipher.getIV()](https://developer.android.com/reference/javax/crypto/Cipher#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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setSignaturePaddings
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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](https://developer.android.com/reference/android/security/keystore/KeyProperties).`SIGNATURE_PADDING`constants.
| Parameters ||
|------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `paddings` | `String`: Value is[KeyProperties.SIGNATURE_PADDING_RSA_PKCS1](https://developer.android.com/reference/android/security/keystore/KeyProperties#SIGNATURE_PADDING_RSA_PKCS1), or[KeyProperties.SIGNATURE_PADDING_RSA_PSS](https://developer.android.com/reference/android/security/keystore/KeyProperties#SIGNATURE_PADDING_RSA_PSS)
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setUnlockedDeviceRequired
Added in[API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setUnlockedDeviceRequired (boolean unlockedDeviceRequired)
```
Sets whether this key is authorized to be used only while the device is unlocked.
The device is considered to be locked for a user when the user's apps are currently inaccessible and some form of lock screen authentication is required to regain access to them. For the full definition, see[KeyguardManager.isDeviceLocked()](https://developer.android.com/reference/android/app/KeyguardManager#isDeviceLocked()).
Public key operations aren't restricted by`setUnlockedDeviceRequired(true)`and may be performed even while the device is locked. In Android 11 (API level 30) and lower, encryption and verification operations with symmetric keys weren't restricted either.
Keys that use`setUnlockedDeviceRequired(true)`can be imported and generated even while the device is locked, as long as the device has been unlocked at least once since the last reboot. However, such keys cannot be used (except for the unrestricted operations mentioned above) until the device is unlocked. Apps that need to encrypt data while the device is locked such that it can only be decrypted while the device is unlocked can generate a key and encrypt the data in software, import the key into Keystore using`setUnlockedDeviceRequired(true)`, and zeroize the original key.
`setUnlockedDeviceRequired(true)`is related to but distinct from[setUserAuthenticationRequired(true)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean)).`setUnlockedDeviceRequired(true)`requires that the device be unlocked, whereas`setUserAuthenticationRequired(true)`requires that a specific type of strong authentication has happened within a specific time period. They may be used together or separately; there are cases in which one requirement can be satisfied but not the other.
**Warning:** Be careful using`setUnlockedDeviceRequired(true)`on Android 14 (API level 34) and lower, since the following bugs existed in Android 12 through 14:
- When the user didn't have a secure lock screen, unlocked-device-required keys couldn't be generated, imported, or used.
- When the user's secure lock screen was removed, all of that user's unlocked-device-required keys were automatically deleted.
- Unlocking the device with a non-strong biometric, such as face on many devices, didn't re-authorize the use of unlocked-device-required keys.
- Unlocking the device with a biometric didn't re-authorize the use of unlocked-device-required keys in profiles that share their parent user's lock.
These issues are fixed in Android 15, so apps can avoid them by using`setUnlockedDeviceRequired(true)`only on Android 15 and higher. Apps that use both`setUnlockedDeviceRequired(true)`and[setUserAuthenticationRequired(true)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))are unaffected by the first two issues, since the first two issues describe expected behavior for`setUserAuthenticationRequired(true)`.
| Parameters ||
|--------------------------|------------------|
| `unlockedDeviceRequired` | `boolean`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setUserAuthenticationParameters
Added in[API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setUserAuthenticationParameters (int timeout,
int type)
```
Sets the duration of time (seconds) and authorization type 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)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))).
By default, if user authentication is required, it must take place for every use of the key.
These cryptographic operations will throw[UserNotAuthenticatedException](https://developer.android.com/reference/android/security/keystore/UserNotAuthenticatedException)during initialization if the user needs to be authenticated to proceed. This situation can be resolved by the user authenticating with the appropriate biometric or credential as required by the key. See[BiometricPrompt.Builder.setAllowedAuthenticators(int)](https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.Builder#setAllowedAuthenticators(int))and[BiometricManager.Authenticators](https://developer.android.com/reference/android/hardware/biometrics/BiometricManager.Authenticators).
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 ||
|-----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `timeout` | `int`: duration in seconds or`0`if user authentication must take place for every use of the key. Value is 0 or greater
|
| `type` | `int`: set of authentication types which can authorize use of the key. See[KeyProperties](https://developer.android.com/reference/android/security/keystore/KeyProperties).`AUTH`flags. Value is either`0`or a combination of[KeyProperties.AUTH_BIOMETRIC_STRONG](https://developer.android.com/reference/android/security/keystore/KeyProperties#AUTH_BIOMETRIC_STRONG), and[KeyProperties.AUTH_DEVICE_CREDENTIAL](https://developer.android.com/reference/android/security/keystore/KeyProperties#AUTH_DEVICE_CREDENTIAL)
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setUserAuthenticationRequired(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))
- [BiometricPrompt](https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt)
- [BiometricPrompt.CryptoObject](https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.CryptoObject)
- [KeyguardManager](https://developer.android.com/reference/android/app/KeyguardManager)
### setUserAuthenticationRequired
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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[KeyguardManager.isDeviceSecure()](https://developer.android.com/reference/android/app/KeyguardManager#isDeviceSecure())). Additionally, if the key requires that user authentication takes place for every use of the key (see[setUserAuthenticationValidityDurationSeconds(int)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidityDurationSeconds(int))), at least one biometric must be enrolled (see[BiometricManager.canAuthenticate()](https://developer.android.com/reference/android/hardware/biometrics/BiometricManager#canAuthenticate())).
- 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 biometric.[More information](https://developer.android.com/training/articles/keystore#UserAuthentication).
- 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 biometric is enrolled or once\\ no more biometrics are enrolled, unless[setInvalidatedByBiometricEnrollment(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setInvalidatedByBiometricEnrollment(boolean))is used to allow validity after enrollment, or`KeyProperties.AUTH_DEVICE_CREDENTIAL`is specified as part of the parameters to[setUserAuthenticationParameters(int, int)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationParameters(int,%20int)). Attempts to initialize cryptographic operations using such keys will throw[KeyPermanentlyInvalidatedException](https://developer.android.com/reference/android/security/keystore/KeyPermanentlyInvalidatedException).
This authorization applies only to secret key and private key operations. Public key operations are not restricted.
| Parameters ||
|------------|------------------|
| `required` | `boolean`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setUserAuthenticationValidityDurationSeconds(int)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidityDurationSeconds(int))
- [KeyguardManager.isDeviceSecure()](https://developer.android.com/reference/android/app/KeyguardManager#isDeviceSecure())
- [BiometricManager.canAuthenticate()](https://developer.android.com/reference/android/hardware/biometrics/BiometricManager#canAuthenticate())
### setUserAuthenticationValidWhileOnBody
Added in[API level 24](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public 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)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationValidityDurationSeconds(int))and[setUserAuthenticationRequired(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#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. If the device does not have an on-body sensor or the key does not have an authentication validity period, this parameter has no effect.
Since Android 12 (API level 31), this parameter has no effect even on devices that have an on-body sensor. A future version of Android may restore enforcement of this parameter. Meanwhile, it is recommended to not use it.
| Parameters ||
|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `remainsValid` | `boolean`: if`true`, and if the device supports enforcement of this parameter, the 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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setUserAuthenticationValidityDurationSeconds
Added in[API level 23](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
Deprecated in[API level 30](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setUserAuthenticationValidityDurationSeconds (int seconds)
```
**This method was deprecated in API level 30.**
See[setUserAuthenticationParameters(int, int)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationParameters(int,%20int))
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)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#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 biometric authentication. This is achieved by initializing a cryptographic operation ([Signature](https://developer.android.com/reference/java/security/Signature),[Cipher](https://developer.android.com/reference/javax/crypto/Cipher),[Mac](https://developer.android.com/reference/javax/crypto/Mac)) with the key, wrapping it into a[BiometricPrompt.CryptoObject](https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.CryptoObject), invoking`BiometricPrompt.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](https://developer.android.com/reference/android/security/keystore/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[KeyguardManager.createConfirmDeviceCredentialIntent(CharSequence, CharSequence)](https://developer.android.com/reference/android/app/KeyguardManager#createConfirmDeviceCredentialIntent(java.lang.CharSequence,%20java.lang.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](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
**See also:**
- [setUserAuthenticationRequired(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))
- [BiometricPrompt](https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt)
- [BiometricPrompt.CryptoObject](https://developer.android.com/reference/android/hardware/biometrics/BiometricPrompt.CryptoObject)
- [KeyguardManager](https://developer.android.com/reference/android/app/KeyguardManager)
### setUserConfirmationRequired
Added in[API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setUserConfirmationRequired (boolean required)
```
Sets whether this key is authorized to be used only for messages confirmed by the user. Confirmation is separate from user authentication (see[setUserAuthenticationRequired(boolean)](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder#setUserAuthenticationRequired(boolean))). Keys can be created that require confirmation but not user authentication, or user authentication but not confirmation, or both. Confirmation verifies that some user with physical possession of the device has approved a displayed message. User authentication verifies that the correct user is present and has authenticated.
This authorization applies only to secret key and private key operations. Public key operations are not restricted. See[ConfirmationPrompt](https://developer.android.com/reference/android/security/ConfirmationPrompt)class for more details about user confirmations.
| Parameters ||
|------------|------------------|
| `required` | `boolean`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|
### setUserPresenceRequired
Added in[API level 28](https://developer.android.com/guide/topics/manifest/uses-sdk-element#ApiLevels)
```
public KeyGenParameterSpec.Builder setUserPresenceRequired (boolean required)
```
Sets whether a test of user presence is required to be performed between the`Signature.initSign()`and`Signature.sign()`method calls. It requires that the KeyStore implementation have a direct way to validate the user presence for example a KeyStore hardware backed strongbox can use a button press that is observable in hardware. A test for user presence is tangential to authentication. The test can be part of an authentication step as long as this step can be validated by the hardware protecting the key and cannot be spoofed. For example, a physical button press can be used as a test of user presence if the other pins connected to the button are not able to simulate a button press.There must be no way for the primary processor to fake a button press, or that button must not be used as a test of user presence.
| Parameters ||
|------------|------------------|
| `required` | `boolean`
|
| Returns ||
|------------------------------------------------------------------------------------------------------------------------------|------------------------------------|
| [KeyGenParameterSpec.Builder](https://developer.android.com/reference/android/security/keystore/KeyGenParameterSpec.Builder) | This value cannot be`null`.
|