content: /*
   * 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.annotation.TestApi;
  import android.annotation.UnsupportedAppUsage;
  import android.app.KeyguardManager;
  import android.hardware.biometrics.BiometricManager;
  import android.hardware.biometrics.BiometricPrompt;
  import android.security.GateKeeper;
  import android.security.KeyStore;
  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), with what parameters (e.g., only with a particular padding scheme or digest), and
   * the key's validity start and end dates. Key use authorizations expressed in the spec apply
   * only to secret keys and private keys -- public keys can be used for any supported operations.
   *
   * <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>Known issues</h3>
   * A known bug in Android 6.0 (API Level 23) causes user authentication-related authorizations to be
   * enforced even for public keys. To work around this issue extract the public key material to use
   * outside of Android Keystore. For example:
   * <pre> {@code
   * PublicKey unrestrictedPublicKey =
   *         KeyFactory.getInstance(publicKey.getAlgorithm()).generatePublic(
   *                 new X509EncodedKeySpec(publicKey.getEncoded()));
   * }</pre>
   *
   * <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 the public key is unrestricted (See Known
   * Issues).
   * <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 the public key is unrestricted.
   * <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 the public key is
   * unrestricted.
   * <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.init(
   *         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.init(
   *         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, UserAuthArgs {
  
      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 mUid;
      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;
      private final boolean mUserPresenceRequired;
      private final byte[] mAttestationChallenge;
      private final boolean mUniqueIdIncluded;
      private final boolean mUserAuthenticationValidWhileOnBody;
      private final boolean mInvalidatedByBiometricEnrollment;
      private final boolean mIsStrongBoxBacked;
      private final boolean mUserConfirmationRequired;
      private final boolean mUnlockedDeviceRequired;
      /*
       * ***NOTE***: All new fields MUST also be added to the following:
       * ParcelableKeyGenParameterSpec class.
       * The KeyGenParameterSpec.Builder constructor that takes a KeyGenParameterSpec
       */
  
      /**
       * @hide should be built with Builder
       */
      public KeyGenParameterSpec(
              String keyStoreAlias,
              int uid,
              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,
              boolean userPresenceRequired,
              byte[] attestationChallenge,
              boolean uniqueIdIncluded,
              boolean userAuthenticationValidWhileOnBody,
              boolean invalidatedByBiometricEnrollment,
              boolean isStrongBoxBacked,
              boolean userConfirmationRequired,
              boolean unlockedDeviceRequired) {
          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;
          mUid = uid;
          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;
          mUserPresenceRequired = userPresenceRequired;
          mUserAuthenticationValidityDurationSeconds = userAuthenticationValidityDurationSeconds;
          mAttestationChallenge = Utils.cloneIfNotNull(attestationChallenge);
          mUniqueIdIncluded = uniqueIdIncluded;
          mUserAuthenticationValidWhileOnBody = userAuthenticationValidWhileOnBody;
          mInvalidatedByBiometricEnrollment = invalidatedByBiometricEnrollment;
          mIsStrongBoxBacked = isStrongBoxBacked;
          mUserConfirmationRequired = userConfirmationRequired;
          mUnlockedDeviceRequired = unlockedDeviceRequired;
      }
  
      /**
       * 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 UID which will own the key. {@code -1} is an alias for the UID of the current
       * process.
       *
       * @hide
       */
      @UnsupportedAppUsage
      public int getUid() {
          return mUid;
      }
  
      /**
       * 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;
      }
  
      /**
       * Returns {@code true} if the key is authorized to be used only for messages confirmed by the
       * user.
       *
       * Confirmation is separate from user authentication (see
       * {@link 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.
       *
       * <p>This authorization applies only to secret key and private key operations. Public key
       * operations are not restricted.
       *
       * @see Builder#setUserConfirmationRequired(boolean)
       */
      public boolean isUserConfirmationRequired() {
          return mUserConfirmationRequired;
      }
  
      /**
       * 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;
      }
  
      /**
       * Returns {@code true} if the key is authorized to be used only if a test of user presence has
       * been performed between the {@code Signature.initSign()} and {@code Signature.sign()} 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.
       */
      public boolean isUserPresenceRequired() {
          return mUserPresenceRequired;
      }
  
      /**
       * Returns the attestation challenge value that will be placed in attestation certificate for
       * this key pair.
       *
       * <p>If this method returns non-{@code null}, the public key certificate for this key pair will
       * contain an extension that describes the details of the key's configuration and
       * authorizations, including the content of the attestation challenge value. If the key is in
       * secure hardware, and if the secure hardware supports attestation, the certificate will be
       * signed by a chain of certificates rooted at a trustworthy CA key. Otherwise the chain will
       * be rooted at an untrusted certificate.
       *
       * <p>If this method returns {@code null}, and the spec is used to generate an asymmetric (RSA
       * or EC) key pair, the public key will have a self-signed certificate if it has purpose {@link
       * KeyProperties#PURPOSE_SIGN}. If does not have purpose {@link KeyProperties#PURPOSE_SIGN}, it
       * will have a fake certificate.
       *
       * <p>Symmetric keys, such as AES and HMAC keys, do not have public key certificates. If a
       * KeyGenParameterSpec with getAttestationChallenge returning non-null is used to generate a
       * symmetric (AES or HMAC) key, {@link javax.crypto.KeyGenerator#generateKey()} will throw
       * {@link java.security.InvalidAlgorithmParameterException}.
       *
       * @see Builder#setAttestationChallenge(byte[])
       */
      public byte[] getAttestationChallenge() {
          return Utils.cloneIfNotNull(mAttestationChallenge);
      }
  
      /**
       * @hide This is a system-only API
       *
       * Returns {@code true} if the attestation certificate will contain a unique ID field.
       */
      @UnsupportedAppUsage
      public boolean isUniqueIdIncluded() {
          return mUniqueIdIncluded;
      }
  
      /**
       * Returns {@code true} if the key will remain authorized only until the device is removed from
       * the user's body, up to the validity duration.  This option has no effect on keys that don't
       * have an authentication validity duration, and has no effect if the device lacks an on-body
       * sensor.
       *
       * <p>Authorization applies only to secret key and private key operations. Public key operations
       * are not restricted.
       *
       * @see #isUserAuthenticationRequired()
       * @see #getUserAuthenticationValidityDurationSeconds()
       * @see Builder#setUserAuthenticationValidWhileOnBody(boolean)
       */
      public boolean isUserAuthenticationValidWhileOnBody() {
          return mUserAuthenticationValidWhileOnBody;
      }
  
      /**
       * Returns {@code true} if the key is irreversibly invalidated when a new biometric is
       * enrolled or all enrolled biometrics are removed. This has effect only for keys that
       * require biometric user authentication for every use.
       *
       * @see #isUserAuthenticationRequired()
       * @see #getUserAuthenticationValidityDurationSeconds()
       * @see Builder#setInvalidatedByBiometricEnrollment(boolean)
       */
      public boolean isInvalidatedByBiometricEnrollment() {
          return mInvalidatedByBiometricEnrollment;
      }
  
      /**
       * Returns {@code true} if the key is protected by a Strongbox security chip.
       */
      public boolean isStrongBoxBacked() {
          return mIsStrongBoxBacked;
      }
  
      /**
       * Returns {@code true} if the screen must be unlocked for this key to be used for decryption or
       * signing. Encryption and signature verification will still be available when the screen is
       * locked.
       *
       * @see Builder#setUnlockedDeviceRequired(boolean)
       */
      public boolean isUnlockedDeviceRequired() {
          return mUnlockedDeviceRequired;
      }
  
      /**
       * @hide
       */
      public long getBoundToSpecificSecureUserId() {
          return GateKeeper.INVALID_SECURE_USER_ID;
      }
  
      /**
       * Builder of {@link KeyGenParameterSpec} instances.
       */
      public final static class Builder {
          private final String mKeystoreAlias;
          private @KeyProperties.PurposeEnum int mPurposes;
  
          private int mUid = KeyStore.UID_SELF;
          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;
          private boolean mUserPresenceRequired = false;
          private byte[] mAttestationChallenge = null;
          private boolean mUniqueIdIncluded = false;
          private boolean mUserAuthenticationValidWhileOnBody;
          private boolean mInvalidatedByBiometricEnrollment = true;
          private boolean mIsStrongBoxBacked = false;
          private boolean mUserConfirmationRequired;
          private boolean mUnlockedDeviceRequired = false;
  
          /**
           * 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;
          }
  
          /**
           * A Builder constructor taking in an already-built KeyGenParameterSpec, useful for
           * changing values of the KeyGenParameterSpec quickly.
           * @hide Should be used internally only.
           */
          public Builder(@NonNull KeyGenParameterSpec sourceSpec) {
              this(sourceSpec.getKeystoreAlias(), sourceSpec.getPurposes());
              mUid = sourceSpec.getUid();
              mKeySize = sourceSpec.getKeySize();
              mSpec = sourceSpec.getAlgorithmParameterSpec();
              mCertificateSubject = sourceSpec.getCertificateSubject();
              mCertificateSerialNumber = sourceSpec.getCertificateSerialNumber();
              mCertificateNotBefore = sourceSpec.getCertificateNotBefore();
              mCertificateNotAfter = sourceSpec.getCertificateNotAfter();
              mKeyValidityStart = sourceSpec.getKeyValidityStart();
              mKeyValidityForOriginationEnd = sourceSpec.getKeyValidityForOriginationEnd();
              mKeyValidityForConsumptionEnd = sourceSpec.getKeyValidityForConsumptionEnd();
              mPurposes = sourceSpec.getPurposes();
              if (sourceSpec.isDigestsSpecified()) {
                  mDigests = sourceSpec.getDigests();
              }
              mEncryptionPaddings = sourceSpec.getEncryptionPaddings();
              mSignaturePaddings = sourceSpec.getSignaturePaddings();
              mBlockModes = sourceSpec.getBlockModes();
              mRandomizedEncryptionRequired = sourceSpec.isRandomizedEncryptionRequired();
              mUserAuthenticationRequired = sourceSpec.isUserAuthenticationRequired();
              mUserAuthenticationValidityDurationSeconds =
                  sourceSpec.getUserAuthenticationValidityDurationSeconds();
              mUserPresenceRequired = sourceSpec.isUserPresenceRequired();
              mAttestationChallenge = sourceSpec.getAttestationChallenge();
              mUniqueIdIncluded = sourceSpec.isUniqueIdIncluded();
              mUserAuthenticationValidWhileOnBody = sourceSpec.isUserAuthenticationValidWhileOnBody();
              mInvalidatedByBiometricEnrollment = sourceSpec.isInvalidatedByBiometricEnrollment();
              mIsStrongBoxBacked = sourceSpec.isStrongBoxBacked();
              mUserConfirmationRequired = sourceSpec.isUserConfirmationRequired();
              mUnlockedDeviceRequired = sourceSpec.isUnlockedDeviceRequired();
          }
  
          /**
           * Sets the UID which will own the key.
           *
           * @param uid UID or {@code -1} for the UID of the current process.
           *
           * @hide
           */
          @NonNull
          public Builder setUid(int uid) {
              mUid = uid;
              return this;
          }
  
          /**
           * 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 biometric
           * must be enrolled (see {@link BiometricManager#canAuthenticate()}).</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 biometric.
           * <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 biometric is enrolled or once\
           * no more biometrics are enrolled, unless {@link
           * #setInvalidatedByBiometricEnrollment(boolean)} is used to allow validity after
           * enrollment. 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 BiometricManager#canAuthenticate()
           */
          @NonNull
          public Builder setUserAuthenticationRequired(boolean required) {
              mUserAuthenticationRequired = required;
              return this;
          }
  
          /**
           * Sets whether this key is authorized to be used only for messages confirmed by the
           * user.
           *
           * Confirmation is separate from user authentication (see
           * {@link #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.
           *
           * <p>This authorization applies only to secret key and private key operations. Public key
           * operations are not restricted.
           *
           * See {@link android.security.ConfirmationPrompt} class for
           * more details about user confirmations.
           */
          @NonNull
          public Builder setUserConfirmationRequired(boolean required) {
              mUserConfirmationRequired = 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 biometric authentication. This is achieved by
           * initializing a cryptographic operation ({@link Signature}, {@link Cipher}, {@link Mac})
           * with the key, wrapping it into a {@link BiometricPrompt.CryptoObject}, invoking
           * {@code BiometricPrompt.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 BiometricPrompt
           * @see BiometricPrompt.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;
          }
  
          /**
           * Sets whether a test of user presence is required to be performed between the
           * {@code Signature.initSign()} and {@code 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.
           */
          @NonNull
          public Builder setUserPresenceRequired(boolean required) {
              mUserPresenceRequired = required;
              return this;
          }
  
          /**
           * 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 {@link java.security.KeyStore#getCertificateChain(String)}.
           *
           * <p>If {@code attestationChallenge} is not {@code 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 {@code 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.
           *
           * <p>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-{@code null} value may be used, including an empty byte
           * array.
           *
           * <p>If {@code attestationChallenge} is {@code 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 {@link android.security.keystore.KeyProperties#PURPOSE_SIGN}. If the key
           * does not have purpose {@link 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 dummy signature.
           *
           * <p>Symmetric keys, such as AES and HMAC keys, do not have public key certificates. If a
           * {@link #getAttestationChallenge()} returns non-null and the spec is used to generate a
           * symmetric (AES or HMAC) key, {@link javax.crypto.KeyGenerator#generateKey()} will throw
           * {@link java.security.InvalidAlgorithmParameterException}.
           */
          @NonNull
          public Builder setAttestationChallenge(byte[] attestationChallenge) {
              mAttestationChallenge = attestationChallenge;
              return this;
          }
  
          /**
           * @hide Only system apps can use this method.
           *
           * Sets whether to include a temporary unique ID field in the attestation certificate.
           */
          @TestApi
          @NonNull
          public Builder setUniqueIdIncluded(boolean uniqueIdIncluded) {
              mUniqueIdIncluded = uniqueIdIncluded;
              return this;
          }
  
          /**
           * 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
           * {@link #setUserAuthenticationValidityDurationSeconds} and
           * {@link #setUserAuthenticationRequired}). 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.
           *
           * <p>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.
           *
           * @param remainsValid if {@code 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.
           */
          @NonNull
          public Builder setUserAuthenticationValidWhileOnBody(boolean remainsValid) {
              mUserAuthenticationValidWhileOnBody = remainsValid;
              return this;
          }
  
          /**
           * Sets whether this key should be invalidated on biometric enrollment.  This
           * applies only to keys which require user authentication (see {@link
           * #setUserAuthenticationRequired(boolean)}) and if no positive validity duration has been
           * set (see {@link #setUserAuthenticationValidityDurationSeconds(int)}, meaning the key is
           * valid for biometric authentication only.
           *
           * <p>By default, {@code invalidateKey} is {@code true}, so keys that are valid for
           * biometric authentication only are <em>irreversibly invalidated</em> when a new
           * biometric is enrolled, or when all existing biometrics are deleted.  That may be
           * changed by calling this method with {@code invalidateKey} set to {@code false}.
           *
           * <p>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.
           */
          @NonNull
          public Builder setInvalidatedByBiometricEnrollment(boolean invalidateKey) {
              mInvalidatedByBiometricEnrollment = invalidateKey;
              return this;
          }
  
          /**
           * Sets whether this key should be protected by a StrongBox security chip.
           */
          @NonNull
          public Builder setIsStrongBoxBacked(boolean isStrongBoxBacked) {
              mIsStrongBoxBacked = isStrongBoxBacked;
              return this;
          }
  
          /**
           * Sets whether the keystore requires the screen to be unlocked before allowing decryption
           * using this key. If this is set to {@code true}, any attempt to decrypt or sign using this
           * key while the screen is locked will fail. A locked device requires a PIN, password,
           * biometric, or other trusted factor to access. While the screen is locked, the key can
           * still be used for encryption or signature verification.
           */
          @NonNull
          public Builder setUnlockedDeviceRequired(boolean unlockedDeviceRequired) {
              mUnlockedDeviceRequired = unlockedDeviceRequired;
              return this;
          }
  
          /**
           * Builds an instance of {@code KeyGenParameterSpec}.
           */
          @NonNull
          public KeyGenParameterSpec build() {
              return new KeyGenParameterSpec(
                      mKeystoreAlias,
                      mUid,
                      mKeySize,
                      mSpec,
                      mCertificateSubject,
                      mCertificateSerialNumber,
                      mCertificateNotBefore,
                      mCertificateNotAfter,
                      mKeyValidityStart,
                      mKeyValidityForOriginationEnd,
                      mKeyValidityForConsumptionEnd,
                      mPurposes,
                      mDigests,
                      mEncryptionPaddings,
                      mSignaturePaddings,
                      mBlockModes,
                      mRandomizedEncryptionRequired,
                      mUserAuthenticationRequired,
                      mUserAuthenticationValidityDurationSeconds,
                      mUserPresenceRequired,
                      mAttestationChallenge,
                      mUniqueIdIncluded,
                      mUserAuthenticationValidWhileOnBody,
                      mInvalidatedByBiometricEnrollment,
                      mIsStrongBoxBacked,
                      mUserConfirmationRequired,
                      mUnlockedDeviceRequired);
          }
      }
  }
  