/*
* Copyright (C) 2012 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.security.keystore;
import android.annotation.IntRange;
import android.annotation.NonNull;
import android.annotation.Nullable;
import android.app.KeyguardManager;
import android.hardware.fingerprint.FingerprintManager;
import android.text.TextUtils;
import java.math.BigInteger;
import java.security.KeyPairGenerator;
import java.security.Signature;
import java.security.cert.Certificate;
import java.security.spec.AlgorithmParameterSpec;
import java.util.Date;
import javax.crypto.Cipher;
import javax.crypto.KeyGenerator;
import javax.crypto.Mac;
import javax.security.auth.x500.X500Principal;
/**
* {@link AlgorithmParameterSpec} for initializing a {@link KeyPairGenerator} or a
* {@link KeyGenerator} of the <a href="{@docRoot}training/articles/keystore.html">Android Keystore
* system</a>. The spec determines authorized uses of the key, such as whether user authentication
* is required for using the key, what operations are authorized (e.g., signing, but not
* decryption) and with what parameters (e.g., only with a particular padding scheme or digest), the
* key's validity start and end dates. Key use authorizations expressed in the spec apply only to
* secret keys and private keys -- public keys can be used for any supported operations.
*
* <p>To generate an asymmetric key pair or a symmetric key, create an instance of this class using
* the {@link Builder}, initialize a {@code KeyPairGenerator} or a {@code KeyGenerator} of the
* desired key type (e.g., {@code EC} or {@code AES} -- see
* {@link KeyProperties}.{@code KEY_ALGORITHM} constants) from the {@code AndroidKeyStore} provider
* with the {@code KeyGenParameterSpec} instance, and then generate a key or key pair using
* {@link KeyGenerator#generateKey()} or {@link KeyPairGenerator#generateKeyPair()}.
*
* <p>The generated key pair or key will be returned by the generator and also stored in the Android
* Keystore under the alias specified in this spec. To obtain the secret or private key from the
* Android Keystore use {@link java.security.KeyStore#getKey(String, char[]) KeyStore.getKey(String, null)}
* or {@link java.security.KeyStore#getEntry(String, java.security.KeyStore.ProtectionParameter) KeyStore.getEntry(String, null)}.
* To obtain the public key from the Android Keystore use
* {@link java.security.KeyStore#getCertificate(String)} and then
* {@link Certificate#getPublicKey()}.
*
* <p>To help obtain algorithm-specific public parameters of key pairs stored in the Android
* Keystore, generated private keys implement {@link java.security.interfaces.ECKey} or
* {@link java.security.interfaces.RSAKey} interfaces whereas public keys implement
* {@link java.security.interfaces.ECPublicKey} or {@link java.security.interfaces.RSAPublicKey}
* interfaces.
*
* <p>For asymmetric key pairs, a self-signed X.509 certificate will be also generated and stored in
* the Android Keystore. This is because the {@link java.security.KeyStore} abstraction does not
* support storing key pairs without a certificate. The subject, serial number, and validity dates
* of the certificate can be customized in this spec. The self-signed certificate may be replaced at
* a later time by a certificate signed by a Certificate Authority (CA).
*
* <p>NOTE: If a private key is not authorized to sign the self-signed certificate, then the
* certificate will be created with an invalid signature which will not verify. Such a certificate
* is still useful because it provides access to the public key. To generate a valid signature for
* the certificate the key needs to be authorized for all of the following:
* <ul>
* <li>{@link KeyProperties#PURPOSE_SIGN},</li>
* <li>operation without requiring the user to be authenticated (see
* {@link Builder#setUserAuthenticationRequired(boolean)}),</li>
* <li>signing/origination at this moment in time (see {@link Builder#setKeyValidityStart(Date)}
* and {@link Builder#setKeyValidityForOriginationEnd(Date)}),</li>
* <li>suitable digest,</li>
* <li>(RSA keys only) padding scheme {@link KeyProperties#SIGNATURE_PADDING_RSA_PKCS1}.</li>
* </ul>
*
* <p>NOTE: The key material of the generated symmetric and private keys is not accessible. The key
* material of the public keys is accessible.
*
* <p>Instances of this class are immutable.
*
* <p><h3>Example: NIST P-256 EC key pair for signing/verification using ECDSA</h3>
* This example illustrates how to generate a NIST P-256 (aka secp256r1 aka prime256v1) EC key pair
* in the Android KeyStore system under alias {@code key1} where the private key is authorized to be
* used only for signing using SHA-256, SHA-384, or SHA-512 digest and only if the user has been
* authenticated within the last five minutes. The use of public key is unrestricted, thus
* permitting signature verification using any padding schemes and digests, and without user
* authentication.
* <pre> {@code
* KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
* KeyProperties.KEY_ALGORITHM_EC, "AndroidKeyStore");
* keyPairGenerator.initialize(
* new KeyGenParameterSpec.Builder(
* "key1",
* KeyProperties.PURPOSE_SIGN)
* .setAlgorithmParameterSpec(new ECGenParameterSpec("secp256r1"))
* .setDigests(KeyProperties.DIGEST_SHA256,
* KeyProperties.DIGEST_SHA384,
* KeyProperties.DIGEST_SHA512)
* // Only permit the private key to be used if the user authenticated
* // within the last five minutes.
* .setUserAuthenticationRequired(true)
* .setUserAuthenticationValidityDurationSeconds(5 * 60)
* .build());
* KeyPair keyPair = keyPairGenerator.generateKeyPair();
* Signature signature = Signature.getInstance("SHA256withECDSA");
* signature.initSign(keyPair.getPrivate());
* ...
*
* // The key pair can also be obtained from the Android Keystore any time as follows:
* KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
* keyStore.load(null);
* PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
* PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
* }</pre>
*
* <p><h3>Example: RSA key pair for signing/verification using RSA-PSS</h3>
* This example illustrates how to generate an RSA key pair in the Android KeyStore system under
* alias {@code key1} authorized to be used only for signing using the RSA-PSS signature padding
* scheme with SHA-256 or SHA-512 digests. The use of public key is unrestricted, thus permitting
* signature verification using any padding schemes and digests.
* <pre> {@code
* KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
* KeyProperties.KEY_ALGORITHM_RSA, "AndroidKeyStore");
* keyPairGenerator.initialize(
* new KeyGenParameterSpec.Builder(
* "key1",
* KeyProperties.PURPOSE_SIGN)
* .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
* .setSignaturePaddings(KeyProperties.SIGNATURE_PADDING_RSA_PSS)
* .build());
* KeyPair keyPair = keyPairGenerator.generateKeyPair();
* Signature signature = Signature.getInstance("SHA256withRSA/PSS");
* signature.initSign(keyPair.getPrivate());
* ...
*
* // The key pair can also be obtained from the Android Keystore any time as follows:
* KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
* keyStore.load(null);
* PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
* PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
* }</pre>
*
* <p><h3>Example: RSA key pair for encryption/decryption using RSA OAEP</h3>
* This example illustrates how to generate an RSA key pair in the Android KeyStore system under
* alias {@code key1} where the private key is authorized to be used only for decryption using RSA
* OAEP encryption padding scheme with SHA-256 or SHA-512 digests. The use of public key is
* unrestricted, thus permitting encryption using any padding schemes and digests.
* <pre> {@code
* KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance(
* KeyProperties.KEY_ALGORITHM_RSA, "AndroidKeyStore");
* keyPairGenerator.initialize(
* new KeyGenParameterSpec.Builder(
* "key1",
* KeyProperties.PURPOSE_DECRYPT)
* .setDigests(KeyProperties.DIGEST_SHA256, KeyProperties.DIGEST_SHA512)
* .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_RSA_OAEP)
* .build());
* KeyPair keyPair = keyPairGenerator.generateKeyPair();
* Cipher cipher = Cipher.getInstance("RSA/ECB/OAEPWithSHA-256AndMGF1Padding");
* cipher.init(Cipher.DECRYPT_MODE, keyPair.getPrivate());
* ...
*
* // The key pair can also be obtained from the Android Keystore any time as follows:
* KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
* keyStore.load(null);
* PrivateKey privateKey = (PrivateKey) keyStore.getKey("key1", null);
* PublicKey publicKey = keyStore.getCertificate("key1").getPublicKey();
* }</pre>
*
* <p><h3>Example: AES key for encryption/decryption in GCM mode</h3>
* The following example illustrates how to generate an AES key in the Android KeyStore system under
* alias {@code key2} authorized to be used only for encryption/decryption in GCM mode with no
* padding.
* <pre> {@code
* KeyGenerator keyGenerator = KeyGenerator.getInstance(
* KeyProperties.KEY_ALGORITHM_AES, "AndroidKeyStore");
* keyGenerator.initialize(
* new KeyGenParameterSpec.Builder("key2",
* KeyProperties.PURPOSE_ENCRYPT | KeyProperties.PURPOSE_DECRYPT)
* .setBlockModes(KeyProperties.BLOCK_MODE_GCM)
* .setEncryptionPaddings(KeyProperties.ENCRYPTION_PADDING_NONE)
* .build());
* SecretKey key = keyGenerator.generateKey();
*
* Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
* cipher.init(Cipher.ENCRYPT_MODE, key);
* ...
*
* // The key can also be obtained from the Android Keystore any time as follows:
* KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
* keyStore.load(null);
* key = (SecretKey) keyStore.getKey("key2", null);
* }</pre>
*
* <p><h3>Example: HMAC key for generating a MAC using SHA-256</h3>
* This example illustrates how to generate an HMAC key in the Android KeyStore system under alias
* {@code key2} authorized to be used only for generating an HMAC using SHA-256.
* <pre> {@code
* KeyGenerator keyGenerator = KeyGenerator.getInstance(
* KeyProperties.KEY_ALGORITHM_HMAC_SHA256, "AndroidKeyStore");
* keyGenerator.initialize(
* new KeyGenParameterSpec.Builder("key2", KeyProperties.PURPOSE_SIGN).build());
* SecretKey key = keyGenerator.generateKey();
* Mac mac = Mac.getInstance("HmacSHA256");
* mac.init(key);
* ...
*
* // The key can also be obtained from the Android Keystore any time as follows:
* KeyStore keyStore = KeyStore.getInstance("AndroidKeyStore");
* keyStore.load(null);
* key = (SecretKey) keyStore.getKey("key2", null);
* }</pre>
*/
public final class KeyGenParameterSpec implements AlgorithmParameterSpec {
private static final X500Principal DEFAULT_CERT_SUBJECT = new X500Principal("CN=fake");
private static final BigInteger DEFAULT_CERT_SERIAL_NUMBER = new BigInteger("1");
private static final Date DEFAULT_CERT_NOT_BEFORE = new Date(0L); // Jan 1 1970
private static final Date DEFAULT_CERT_NOT_AFTER = new Date(2461449600000L); // Jan 1 2048
private final String mKeystoreAlias;
private final int mKeySize;
private final AlgorithmParameterSpec mSpec;
private final X500Principal mCertificateSubject;
private final BigInteger mCertificateSerialNumber;
private final Date mCertificateNotBefore;
private final Date mCertificateNotAfter;
private final Date mKeyValidityStart;
private final Date mKeyValidityForOriginationEnd;
private final Date mKeyValidityForConsumptionEnd;
private final @KeyProperties.PurposeEnum int mPurposes;
private final @KeyProperties.DigestEnum String[] mDigests;
private final @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
private final @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
private final @KeyProperties.BlockModeEnum String[] mBlockModes;
private final boolean mRandomizedEncryptionRequired;
private final boolean mUserAuthenticationRequired;
private final int mUserAuthenticationValidityDurationSeconds;
/**
* @hide should be built with Builder
*/
public KeyGenParameterSpec(
String keyStoreAlias,
int keySize,
AlgorithmParameterSpec spec,
X500Principal certificateSubject,
BigInteger certificateSerialNumber,
Date certificateNotBefore,
Date certificateNotAfter,
Date keyValidityStart,
Date keyValidityForOriginationEnd,
Date keyValidityForConsumptionEnd,
@KeyProperties.PurposeEnum int purposes,
@KeyProperties.DigestEnum String[] digests,
@KeyProperties.EncryptionPaddingEnum String[] encryptionPaddings,
@KeyProperties.SignaturePaddingEnum String[] signaturePaddings,
@KeyProperties.BlockModeEnum String[] blockModes,
boolean randomizedEncryptionRequired,
boolean userAuthenticationRequired,
int userAuthenticationValidityDurationSeconds) {
if (TextUtils.isEmpty(keyStoreAlias)) {
throw new IllegalArgumentException("keyStoreAlias must not be empty");
}
if (certificateSubject == null) {
certificateSubject = DEFAULT_CERT_SUBJECT;
}
if (certificateNotBefore == null) {
certificateNotBefore = DEFAULT_CERT_NOT_BEFORE;
}
if (certificateNotAfter == null) {
certificateNotAfter = DEFAULT_CERT_NOT_AFTER;
}
if (certificateSerialNumber == null) {
certificateSerialNumber = DEFAULT_CERT_SERIAL_NUMBER;
}
if (certificateNotAfter.before(certificateNotBefore)) {
throw new IllegalArgumentException("certificateNotAfter < certificateNotBefore");
}
mKeystoreAlias = keyStoreAlias;
mKeySize = keySize;
mSpec = spec;
mCertificateSubject = certificateSubject;
mCertificateSerialNumber = certificateSerialNumber;
mCertificateNotBefore = Utils.cloneIfNotNull(certificateNotBefore);
mCertificateNotAfter = Utils.cloneIfNotNull(certificateNotAfter);
mKeyValidityStart = Utils.cloneIfNotNull(keyValidityStart);
mKeyValidityForOriginationEnd = Utils.cloneIfNotNull(keyValidityForOriginationEnd);
mKeyValidityForConsumptionEnd = Utils.cloneIfNotNull(keyValidityForConsumptionEnd);
mPurposes = purposes;
mDigests = ArrayUtils.cloneIfNotEmpty(digests);
mEncryptionPaddings =
ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(encryptionPaddings));
mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(signaturePaddings));
mBlockModes = ArrayUtils.cloneIfNotEmpty(ArrayUtils.nullToEmpty(blockModes));
mRandomizedEncryptionRequired = randomizedEncryptionRequired;
mUserAuthenticationRequired = userAuthenticationRequired;
mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
}
/**
* Returns the alias that will be used in the {@code java.security.KeyStore}
* in conjunction with the {@code AndroidKeyStore}.
*/
@NonNull
public String getKeystoreAlias() {
return mKeystoreAlias;
}
/**
* Returns the requested key size. If {@code -1}, the size should be looked up from
* {@link #getAlgorithmParameterSpec()}, if provided, otherwise an algorithm-specific default
* size should be used.
*/
public int getKeySize() {
return mKeySize;
}
/**
* Returns the key algorithm-specific {@link AlgorithmParameterSpec} that will be used for
* creation of the key or {@code null} if algorithm-specific defaults should be used.
*/
@Nullable
public AlgorithmParameterSpec getAlgorithmParameterSpec() {
return mSpec;
}
/**
* Returns the subject distinguished name to be used on the X.509 certificate that will be put
* in the {@link java.security.KeyStore}.
*/
@NonNull
public X500Principal getCertificateSubject() {
return mCertificateSubject;
}
/**
* Returns the serial number to be used on the X.509 certificate that will be put in the
* {@link java.security.KeyStore}.
*/
@NonNull
public BigInteger getCertificateSerialNumber() {
return mCertificateSerialNumber;
}
/**
* Returns the start date to be used on the X.509 certificate that will be put in the
* {@link java.security.KeyStore}.
*/
@NonNull
public Date getCertificateNotBefore() {
return Utils.cloneIfNotNull(mCertificateNotBefore);
}
/**
* Returns the end date to be used on the X.509 certificate that will be put in the
* {@link java.security.KeyStore}.
*/
@NonNull
public Date getCertificateNotAfter() {
return Utils.cloneIfNotNull(mCertificateNotAfter);
}
/**
* Returns the time instant before which the key is not yet valid or {@code null} if not
* restricted.
*/
@Nullable
public Date getKeyValidityStart() {
return Utils.cloneIfNotNull(mKeyValidityStart);
}
/**
* Returns the time instant after which the key is no longer valid for decryption and
* verification or {@code null} if not restricted.
*/
@Nullable
public Date getKeyValidityForConsumptionEnd() {
return Utils.cloneIfNotNull(mKeyValidityForConsumptionEnd);
}
/**
* Returns the time instant after which the key is no longer valid for encryption and signing
* or {@code null} if not restricted.
*/
@Nullable
public Date getKeyValidityForOriginationEnd() {
return Utils.cloneIfNotNull(mKeyValidityForOriginationEnd);
}
/**
* Returns the set of purposes (e.g., encrypt, decrypt, sign) for which the key can be used.
* Attempts to use the key for any other purpose will be rejected.
*
* <p>See {@link KeyProperties}.{@code PURPOSE} flags.
*/
public @KeyProperties.PurposeEnum int getPurposes() {
return mPurposes;
}
/**
* Returns the set of digest algorithms (e.g., {@code SHA-256}, {@code SHA-384} with which the
* key can be used or {@code null} if not specified.
*
* <p>See {@link KeyProperties}.{@code DIGEST} constants.
*
* @throws IllegalStateException if this set has not been specified.
*
* @see #isDigestsSpecified()
*/
@NonNull
public @KeyProperties.DigestEnum String[] getDigests() {
if (mDigests == null) {
throw new IllegalStateException("Digests not specified");
}
return ArrayUtils.cloneIfNotEmpty(mDigests);
}
/**
* Returns {@code true} if the set of digest algorithms with which the key can be used has been
* specified.
*
* @see #getDigests()
*/
@NonNull
public boolean isDigestsSpecified() {
return mDigests != null;
}
/**
* Returns the set of padding schemes (e.g., {@code PKCS7Padding}, {@code OEAPPadding},
* {@code PKCS1Padding}, {@code NoPadding}) with which the key can be used when
* encrypting/decrypting. Attempts to use the key with any other padding scheme will be
* rejected.
*
* <p>See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
*/
@NonNull
public @KeyProperties.EncryptionPaddingEnum String[] getEncryptionPaddings() {
return ArrayUtils.cloneIfNotEmpty(mEncryptionPaddings);
}
/**
* Gets the set of padding schemes (e.g., {@code PSS}, {@code 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.
*
* <p>See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
*/
@NonNull
public @KeyProperties.SignaturePaddingEnum String[] getSignaturePaddings() {
return ArrayUtils.cloneIfNotEmpty(mSignaturePaddings);
}
/**
* Gets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be used
* when encrypting/decrypting. Attempts to use the key with any other block modes will be
* rejected.
*
* <p>See {@link KeyProperties}.{@code BLOCK_MODE} constants.
*/
@NonNull
public @KeyProperties.BlockModeEnum String[] getBlockModes() {
return ArrayUtils.cloneIfNotEmpty(mBlockModes);
}
/**
* Returns {@code true} if encryption using this key must be sufficiently randomized to produce
* different ciphertexts for the same plaintext every time. The formal cryptographic property
* being required is <em>indistinguishability under chosen-plaintext attack ({@code
* IND-CPA})</em>. 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.
*/
public boolean isRandomizedEncryptionRequired() {
return mRandomizedEncryptionRequired;
}
/**
* Returns {@code true} if the key is authorized to be used only if the user has been
* authenticated.
*
* <p>This authorization applies only to secret key and private key operations. Public key
* operations are not restricted.
*
* @see #getUserAuthenticationValidityDurationSeconds()
* @see Builder#setUserAuthenticationRequired(boolean)
*/
public boolean isUserAuthenticationRequired() {
return mUserAuthenticationRequired;
}
/**
* Gets the duration of time (seconds) for which this key is authorized to be used after the
* user is successfully authenticated. This has effect only if user authentication is required
* (see {@link #isUserAuthenticationRequired()}).
*
* <p>This authorization applies only to secret key and private key operations. Public key
* operations are not restricted.
*
* @return duration in seconds or {@code -1} if authentication is required for every use of the
* key.
*
* @see #isUserAuthenticationRequired()
* @see Builder#setUserAuthenticationValidityDurationSeconds(int)
*/
public int getUserAuthenticationValidityDurationSeconds() {
return mUserAuthenticationValidityDurationSeconds;
}
/**
* Builder of {@link KeyGenParameterSpec} instances.
*/
public final static class Builder {
private final String mKeystoreAlias;
private @KeyProperties.PurposeEnum int mPurposes;
private int mKeySize = -1;
private AlgorithmParameterSpec mSpec;
private X500Principal mCertificateSubject;
private BigInteger mCertificateSerialNumber;
private Date mCertificateNotBefore;
private Date mCertificateNotAfter;
private Date mKeyValidityStart;
private Date mKeyValidityForOriginationEnd;
private Date mKeyValidityForConsumptionEnd;
private @KeyProperties.DigestEnum String[] mDigests;
private @KeyProperties.EncryptionPaddingEnum String[] mEncryptionPaddings;
private @KeyProperties.SignaturePaddingEnum String[] mSignaturePaddings;
private @KeyProperties.BlockModeEnum String[] mBlockModes;
private boolean mRandomizedEncryptionRequired = true;
private boolean mUserAuthenticationRequired;
private int mUserAuthenticationValidityDurationSeconds = -1;
/**
* Creates a new instance of the {@code Builder}.
*
* @param keystoreAlias alias of the entry in which the generated key will appear in
* Android KeyStore. Must not be empty.
* @param 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.
*
* <p>If the set of purposes for which the key can be used does not contain
* {@link KeyProperties#PURPOSE_SIGN}, the self-signed certificate generated by
* {@link KeyPairGenerator} of {@code AndroidKeyStore} provider will contain an
* invalid signature. This is OK if the certificate is only used for obtaining the
* public key from Android KeyStore.
*
* <p>See {@link KeyProperties}.{@code PURPOSE} flags.
*/
public Builder(@NonNull String keystoreAlias, @KeyProperties.PurposeEnum int purposes) {
if (keystoreAlias == null) {
throw new NullPointerException("keystoreAlias == null");
} else if (keystoreAlias.isEmpty()) {
throw new IllegalArgumentException("keystoreAlias must not be empty");
}
mKeystoreAlias = keystoreAlias;
mPurposes = purposes;
}
/**
* 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.
*
* <p>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
* {@link #setAlgorithmParameterSpec(AlgorithmParameterSpec) setAlgorithmParameterSpec}.
*/
@NonNull
public Builder setKeySize(int keySize) {
if (keySize < 0) {
throw new IllegalArgumentException("keySize < 0");
}
mKeySize = keySize;
return this;
}
/**
* Sets the algorithm-specific key generation parameters. For example, for RSA keys this may
* be an instance of {@link java.security.spec.RSAKeyGenParameterSpec} whereas for EC keys
* this may be an instance of {@link java.security.spec.ECGenParameterSpec}.
*
* <p>These key generation parameters must match other explicitly set parameters (if any),
* such as key size.
*/
public Builder setAlgorithmParameterSpec(@NonNull AlgorithmParameterSpec spec) {
if (spec == null) {
throw new NullPointerException("spec == null");
}
mSpec = spec;
return this;
}
/**
* Sets the subject used for the self-signed certificate of the generated key pair.
*
* <p>By default, the subject is {@code CN=fake}.
*/
@NonNull
public Builder setCertificateSubject(@NonNull X500Principal subject) {
if (subject == null) {
throw new NullPointerException("subject == null");
}
mCertificateSubject = subject;
return this;
}
/**
* Sets the serial number used for the self-signed certificate of the generated key pair.
*
* <p>By default, the serial number is {@code 1}.
*/
@NonNull
public Builder setCertificateSerialNumber(@NonNull BigInteger serialNumber) {
if (serialNumber == null) {
throw new NullPointerException("serialNumber == null");
}
mCertificateSerialNumber = serialNumber;
return this;
}
/**
* Sets the start of the validity period for the self-signed certificate of the generated
* key pair.
*
* <p>By default, this date is {@code Jan 1 1970}.
*/
@NonNull
public Builder setCertificateNotBefore(@NonNull Date date) {
if (date == null) {
throw new NullPointerException("date == null");
}
mCertificateNotBefore = Utils.cloneIfNotNull(date);
return this;
}
/**
* Sets the end of the validity period for the self-signed certificate of the generated key
* pair.
*
* <p>By default, this date is {@code Jan 1 2048}.
*/
@NonNull
public Builder setCertificateNotAfter(@NonNull Date date) {
if (date == null) {
throw new NullPointerException("date == null");
}
mCertificateNotAfter = Utils.cloneIfNotNull(date);
return this;
}
/**
* Sets the time instant before which the key is not yet valid.
*
* <p>By default, the key is valid at any instant.
*
* @see #setKeyValidityEnd(Date)
*/
@NonNull
public Builder setKeyValidityStart(Date startDate) {
mKeyValidityStart = Utils.cloneIfNotNull(startDate);
return this;
}
/**
* Sets the time instant after which the key is no longer valid.
*
* <p>By default, the key is valid at any instant.
*
* @see #setKeyValidityStart(Date)
* @see #setKeyValidityForConsumptionEnd(Date)
* @see #setKeyValidityForOriginationEnd(Date)
*/
@NonNull
public Builder setKeyValidityEnd(Date endDate) {
setKeyValidityForOriginationEnd(endDate);
setKeyValidityForConsumptionEnd(endDate);
return this;
}
/**
* Sets the time instant after which the key is no longer valid for encryption and signing.
*
* <p>By default, the key is valid at any instant.
*
* @see #setKeyValidityForConsumptionEnd(Date)
*/
@NonNull
public Builder setKeyValidityForOriginationEnd(Date endDate) {
mKeyValidityForOriginationEnd = Utils.cloneIfNotNull(endDate);
return this;
}
/**
* Sets the time instant after which the key is no longer valid for decryption and
* verification.
*
* <p>By default, the key is valid at any instant.
*
* @see #setKeyValidityForOriginationEnd(Date)
*/
@NonNull
public Builder setKeyValidityForConsumptionEnd(Date endDate) {
mKeyValidityForConsumptionEnd = Utils.cloneIfNotNull(endDate);
return this;
}
/**
* Sets the set of digests algorithms (e.g., {@code SHA-256}, {@code SHA-384}) with which
* the key can be used. Attempts to use the key with any other digest algorithm will be
* rejected.
*
* <p>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.,
* {@code SHA-256} for key algorithm {@code HmacSHA256}). HMAC keys cannot be authorized
* for more than one digest.
*
* <p>For private keys used for TLS/SSL client or server authentication it is usually
* necessary to authorize the use of no digest ({@link 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.
*
* <p>See {@link KeyProperties}.{@code DIGEST} constants.
*/
@NonNull
public Builder setDigests(@KeyProperties.DigestEnum String... digests) {
mDigests = ArrayUtils.cloneIfNotEmpty(digests);
return this;
}
/**
* Sets the set of padding schemes (e.g., {@code PKCS7Padding}, {@code OAEPPadding},
* {@code PKCS1Padding}, {@code NoPadding}) with which the key can be used when
* encrypting/decrypting. Attempts to use the key with any other padding scheme will be
* rejected.
*
* <p>This must be specified for keys which are used for encryption/decryption.
*
* <p>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
* ({@link KeyProperties#ENCRYPTION_PADDING_NONE}) and/or PKCS#1 encryption padding
* ({@link 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.
*
* <p>See {@link KeyProperties}.{@code ENCRYPTION_PADDING} constants.
*/
@NonNull
public Builder setEncryptionPaddings(
@KeyProperties.EncryptionPaddingEnum String... paddings) {
mEncryptionPaddings = ArrayUtils.cloneIfNotEmpty(paddings);
return this;
}
/**
* Sets the set of padding schemes (e.g., {@code PSS}, {@code 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.
*
* <p>This must be specified for RSA keys which are used for signing/verification.
*
* <p>See {@link KeyProperties}.{@code SIGNATURE_PADDING} constants.
*/
@NonNull
public Builder setSignaturePaddings(
@KeyProperties.SignaturePaddingEnum String... paddings) {
mSignaturePaddings = ArrayUtils.cloneIfNotEmpty(paddings);
return this;
}
/**
* Sets the set of block modes (e.g., {@code GCM}, {@code CBC}) with which the key can be
* used when encrypting/decrypting. Attempts to use the key with any other block modes will
* be rejected.
*
* <p>This must be specified for symmetric encryption/decryption keys.
*
* <p>See {@link KeyProperties}.{@code BLOCK_MODE} constants.
*/
@NonNull
public Builder setBlockModes(@KeyProperties.BlockModeEnum String... blockModes) {
mBlockModes = ArrayUtils.cloneIfNotEmpty(blockModes);
return this;
}
/**
* 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 <em>indistinguishability under chosen-plaintext attack
* ({@code IND-CPA})</em>. 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.
*
* <p>By default, {@code IND-CPA} is required.
*
* <p>When {@code IND-CPA} is required:
* <ul>
* <li>encryption/decryption transformation which do not offer {@code IND-CPA}, such as
* {@code ECB} with a symmetric encryption algorithm, or RSA encryption/decryption without
* padding, are prohibited;</li>
* <li>in block modes which use an IV, such as {@code GCM}, {@code CBC}, and {@code CTR},
* caller-provided IVs are rejected when encrypting, to ensure that only random IVs are
* used.</li>
* </ul>
*
* <p>Before disabling this requirement, consider the following approaches instead:
* <ul>
* <li>If you are generating a random IV for encryption and then initializing a {@code}
* Cipher using the IV, the solution is to let the {@code Cipher} generate a random IV
* instead. This will occur if the {@code Cipher} is initialized for encryption without an
* IV. The IV can then be queried via {@link Cipher#getIV()}.</li>
* <li>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.</li>
* <li>If you are using RSA encryption without padding, consider switching to encryption
* padding schemes which offer {@code IND-CPA}, such as PKCS#1 or OAEP.</li>
* </ul>
*/
@NonNull
public Builder setRandomizedEncryptionRequired(boolean required) {
mRandomizedEncryptionRequired = required;
return this;
}
/**
* Sets whether this key is authorized to be used only if the user has been authenticated.
*
* <p>By default, the key is authorized to be used regardless of whether the user has been
* authenticated.
*
* <p>When user authentication is required:
* <ul>
* <li>The key can only be generated if secure lock screen is set up (see
* {@link KeyguardManager#isDeviceSecure()}). Additionally, if the key requires that user
* authentication takes place for every use of the key (see
* {@link #setUserAuthenticationValidityDurationSeconds(int)}), at least one fingerprint
* must be enrolled (see {@link FingerprintManager#hasEnrolledFingerprints()}).</li>
* <li>The use of the key must be authorized by the user by authenticating to this Android
* device using a subset of their secure lock screen credentials such as
* password/PIN/pattern or fingerprint.
* <a href="{@docRoot}training/articles/keystore.html#UserAuthentication">More
* information</a>.
* <li>The key will become <em>irreversibly invalidated</em> once the secure lock screen is
* disabled (reconfigured to None, Swipe or other mode which does not authenticate the user)
* or when the secure lock screen is forcibly reset (e.g., by a Device Administrator).
* Additionally, if the key requires that user authentication takes place for every use of
* the key, it is also irreversibly invalidated once a new fingerprint is enrolled or once\
* no more fingerprints are enrolled. Attempts to initialize cryptographic operations using
* such keys will throw {@link KeyPermanentlyInvalidatedException}.</li>
* </ul>
*
* <p>This authorization applies only to secret key and private key operations. Public key
* operations are not restricted.
*
* @see #setUserAuthenticationValidityDurationSeconds(int)
* @see KeyguardManager#isDeviceSecure()
* @see FingerprintManager#hasEnrolledFingerprints()
*/
@NonNull
public Builder setUserAuthenticationRequired(boolean required) {
mUserAuthenticationRequired = required;
return this;
}
/**
* 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 {@link #setUserAuthenticationRequired(boolean)}).
*
* <p>By default, if user authentication is required, it must take place for every use of
* the key.
*
* <p>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 ({@link Signature}, {@link Cipher}, {@link Mac})
* with the key, wrapping it into a {@link FingerprintManager.CryptoObject}, invoking
* {@code FingerprintManager.authenticate} with {@code CryptoObject}, and proceeding with
* the cryptographic operation only if the authentication flow succeeds.
*
* <p>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
* {@link 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
* {@link 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.
*
* @param seconds duration in seconds or {@code -1} if user authentication must take place
* for every use of the key.
*
* @see #setUserAuthenticationRequired(boolean)
* @see FingerprintManager
* @see FingerprintManager.CryptoObject
* @see KeyguardManager
*/
@NonNull
public Builder setUserAuthenticationValidityDurationSeconds(
@IntRange(from = -1) int seconds) {
if (seconds < -1) {
throw new IllegalArgumentException("seconds must be -1 or larger");
}
mUserAuthenticationValidityDurationSeconds = seconds;
return this;
}
/**
* Builds an instance of {@code KeyGenParameterSpec}.
*/
@NonNull
public KeyGenParameterSpec build() {
return new KeyGenParameterSpec(
mKeystoreAlias,
mKeySize,
mSpec,
mCertificateSubject,
mCertificateSerialNumber,
mCertificateNotBefore,
mCertificateNotAfter,
mKeyValidityStart,
mKeyValidityForOriginationEnd,
mKeyValidityForConsumptionEnd,
mPurposes,
mDigests,
mEncryptionPaddings,
mSignaturePaddings,
mBlockModes,
mRandomizedEncryptionRequired,
mUserAuthenticationRequired,
mUserAuthenticationValidityDurationSeconds);
}
}
}