KeyProtection.Builder

Creates a new instance of the Builder.

Builds an instance of KeyProtection.

Sets the set of block modes (e.g., GCM, CBC) with which the key can be used when encrypting/decrypting. Attempts to use the key with any other block modes will be rejected.

This must be specified for symmetric encryption/decryption keys.

See KeyProperties.BLOCK_MODE constants.

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

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

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

See KeyProperties.DIGEST constants.

Sets the set of padding schemes (e.g., OAEPPadding, PKCS7Padding, NoPadding) with which the key can be used when encrypting/decrypting. Attempts to use the key with any other padding scheme will be rejected.

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

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

See KeyProperties.ENCRYPTION_PADDING constants.

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

By default, the key is valid at any instant.

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

By default, the key is valid at any instant.

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

By default, the key is valid at any instant.

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

By default, the key is valid at any instant.

Sets whether encryption using this key must be sufficiently randomized to produce different ciphertexts for the same plaintext every time. The formal cryptographic property being required is indistinguishability under chosen-plaintext attack (IND-CPA). This property is important because it mitigates several classes of weaknesses due to which ciphertext may leak information about plaintext. For example, if a given plaintext always produces the same ciphertext, an attacker may see the repeated ciphertexts and be able to deduce something about the plaintext.

By default, IND-CPA is required.

When IND-CPA is required:

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

Before disabling this requirement, consider the following approaches instead:

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

Sets the set of padding schemes (e.g., PSS, PKCS#1) with which the key can be used when signing/verifying. Attempts to use the key with any other padding scheme will be rejected.

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

See KeyProperties.SIGNATURE_PADDING constants.

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

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

When user authentication is required:

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

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

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

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

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

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