public static final class KeyGenParameterSpec.Builder extends Object
KeyGenParameterSpec
instances.Constructor and Description |
---|
Builder(String keystoreAlias,
int purposes)
Creates a new instance of the
Builder . |
Modifier and Type | Method and Description |
---|---|
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 |
setUid(int uid)
Sets the UID which will own the key.
|
KeyGenParameterSpec.Builder |
setUniqueIdIncluded(boolean uniqueIdIncluded) |
KeyGenParameterSpec.Builder |
setUserAuthenticationRequired(boolean required)
Sets whether this key is authorized to be used only if the user has been authenticated.
|
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.
|
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) ). |
public Builder(String keystoreAlias, int purposes)
Builder
.keystoreAlias
- alias of the entry in which the generated key will appear in
Android KeyStore. Must not be empty.purposes
- 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
KeyProperties.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 KeyGenParameterSpec.Builder setUid(int uid)
uid
- UID or -1
for the UID of the current process.public KeyGenParameterSpec.Builder setKeySize(int keySize)
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
.
public KeyGenParameterSpec.Builder setAlgorithmParameterSpec(AlgorithmParameterSpec spec)
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.
public KeyGenParameterSpec.Builder setCertificateSubject(X500Principal subject)
By default, the subject is CN=fake
.
public KeyGenParameterSpec.Builder setCertificateSerialNumber(BigInteger serialNumber)
By default, the serial number is 1
.
public KeyGenParameterSpec.Builder setCertificateNotBefore(Date date)
By default, this date is Jan 1 1970
.
public KeyGenParameterSpec.Builder setCertificateNotAfter(Date date)
By default, this date is Jan 1 2048
.
public KeyGenParameterSpec.Builder setKeyValidityStart(Date startDate)
By default, the key is valid at any instant.
setKeyValidityEnd(Date)
public KeyGenParameterSpec.Builder setKeyValidityEnd(Date endDate)
By default, the key is valid at any instant.
public KeyGenParameterSpec.Builder setKeyValidityForOriginationEnd(Date endDate)
By default, the key is valid at any instant.
setKeyValidityForConsumptionEnd(Date)
public KeyGenParameterSpec.Builder setKeyValidityForConsumptionEnd(Date endDate)
By default, the key is valid at any instant.
setKeyValidityForOriginationEnd(Date)
public KeyGenParameterSpec.Builder setDigests(String... digests)
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
). 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.
public KeyGenParameterSpec.Builder setEncryptionPaddings(String... paddings)
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
) and/or PKCS#1 encryption padding
(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
.ENCRYPTION_PADDING
constants.
public KeyGenParameterSpec.Builder setSignaturePaddings(String... paddings)
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.
public KeyGenParameterSpec.Builder setBlockModes(String... blockModes)
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.
public KeyGenParameterSpec.Builder setRandomizedEncryptionRequired(boolean required)
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:
IND-CPA
, such as
ECB
with a symmetric encryption algorithm, or RSA encryption/decryption without
padding, are prohibited;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:
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()
.IND-CPA
, such as PKCS#1 or OAEP.public KeyGenParameterSpec.Builder setUserAuthenticationRequired(boolean required)
By default, the key is authorized to be used regardless of whether the user has been authenticated.
When user authentication is required:
KeyguardManager.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 FingerprintManager.hasEnrolledFingerprints()
).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.
public KeyGenParameterSpec.Builder setUserAuthenticationValidityDurationSeconds(int seconds)
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
KeyguardManager.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.
seconds
- duration in seconds or -1
if user authentication must take place
for every use of the key.setUserAuthenticationRequired(boolean)
,
FingerprintManager
,
FingerprintManager.CryptoObject
,
KeyguardManager
public KeyGenParameterSpec.Builder setAttestationChallenge(byte[] attestationChallenge)
KeyStore.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 KeyProperties.PURPOSE_SIGN
. If the key
does not have purpose KeyProperties.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
KeyGenParameterSpec.getAttestationChallenge()
returns non-null and the spec is used to generate a
symmetric (AES or HMAC) key, KeyGenerator.generateKey()
will throw
InvalidAlgorithmParameterException
.
public KeyGenParameterSpec.Builder setUniqueIdIncluded(boolean uniqueIdIncluded)
public KeyGenParameterSpec.Builder setUserAuthenticationValidWhileOnBody(boolean remainsValid)
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.
remainsValid
- 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.public KeyGenParameterSpec.Builder setInvalidatedByBiometricEnrollment(boolean invalidateKey)
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.
public KeyGenParameterSpec build()
KeyGenParameterSpec
.