MasterKey.Builder

public static final class MasterKey.Builder
extends Object

java.lang.Object
   ↳ androidx.security.crypto.MasterKey.Builder


Builder for generating a MasterKey.

Summary

Public constructors

Builder(Context context)

Creates a builder for a MasterKey using the default alias of MasterKey.DEFAULT_MASTER_KEY_ALIAS.

Builder(Context context, String keyAlias)

Creates a builder for a MasterKey.

Public methods

MasterKey build()

Builds a MasterKey from this builder.

MasterKey.Builder setKeyGenParameterSpec(KeyGenParameterSpec keyGenParameterSpec)

Sets a custom KeyGenParameterSpec to use as the basis of the master key.

MasterKey.Builder setKeyScheme(MasterKey.KeyScheme keyScheme)

Sets a MasterKey.KeyScheme to be used for the master key.

MasterKey.Builder setRequestStrongBoxBacked(boolean requestStrongBoxBacked)

Sets whether or not to request this key is strong box backed.

MasterKey.Builder setUserAuthenticationRequired(boolean authenticationRequired)

When used with setKeyScheme(KeyScheme), sets that the built master key should require the user to authenticate before it's unlocked, probably using the androidx.biometric library.

MasterKey.Builder setUserAuthenticationRequired(boolean authenticationRequired, int userAuthenticationValidityDurationSeconds)

When used with setKeyScheme(KeyScheme), sets that the built master key should require the user to authenticate before it's unlocked, probably using the androidx.biometric library, and that the key should remain unlocked for the provided duration.

Inherited methods

Public constructors

Builder

public Builder (Context context)

Creates a builder for a MasterKey using the default alias of MasterKey.DEFAULT_MASTER_KEY_ALIAS.

Parameters
context Context: The context to use with this master key.

Builder

public Builder (Context context, 
                String keyAlias)

Creates a builder for a MasterKey.

Parameters
context Context: The context to use with this master key.

keyAlias String

Public methods

build

public MasterKey build ()

Builds a MasterKey from this builder.

Returns
MasterKey The master key.

Throws
GeneralSecurityException
IOException

setKeyGenParameterSpec

public MasterKey.Builder setKeyGenParameterSpec (KeyGenParameterSpec keyGenParameterSpec)

Sets a custom KeyGenParameterSpec to use as the basis of the master key. NOTE: Either this method OR setKeyScheme(KeyScheme) should be used to set the parameters to use for building the master key. Calling either function after the other will throw an IllegalArgumentException.

Parameters
keyGenParameterSpec KeyGenParameterSpec: The key spec to use.

Returns
MasterKey.Builder This builder.

setKeyScheme

public MasterKey.Builder setKeyScheme (MasterKey.KeyScheme keyScheme)

Sets a MasterKey.KeyScheme to be used for the master key. This uses a default KeyGenParameterSpec associated with the provided KeyScheme. NOTE: Either this method OR setKeyGenParameterSpec(KeyGenParameterSpec) should be used to set the parameters to use for building the master key. Calling either function after the other will throw an IllegalArgumentException.

Parameters
keyScheme MasterKey.KeyScheme: The KeyScheme to use.

Returns
MasterKey.Builder This builder.

setRequestStrongBoxBacked

public MasterKey.Builder setRequestStrongBoxBacked (boolean requestStrongBoxBacked)

Sets whether or not to request this key is strong box backed. This setting is only applicable on Build.VERSION_CODES.P and above, and only on devices that support Strongbox.

Parameters
requestStrongBoxBacked boolean: Whether to request to use strongbox

Returns
MasterKey.Builder This builder.

setUserAuthenticationRequired

public MasterKey.Builder setUserAuthenticationRequired (boolean authenticationRequired)

When used with setKeyScheme(KeyScheme), sets that the built master key should require the user to authenticate before it's unlocked, probably using the androidx.biometric library. This method sets the validity duration of the key to MasterKey.getDefaultAuthenticationValidityDurationSeconds().

Parameters
authenticationRequired boolean: Whether user authentication should be required to use the key.

Returns
MasterKey.Builder This builder.

setUserAuthenticationRequired

public MasterKey.Builder setUserAuthenticationRequired (boolean authenticationRequired, 
                int userAuthenticationValidityDurationSeconds)

When used with setKeyScheme(KeyScheme), sets that the built master key should require the user to authenticate before it's unlocked, probably using the androidx.biometric library, and that the key should remain unlocked for the provided duration.

Parameters
authenticationRequired boolean: Whether user authentication should be required to use the key.

userAuthenticationValidityDurationSeconds int: Duration in seconds that the key should remain unlocked following user authentication.

Value is 1 or greater.

Returns
MasterKey.Builder This builder.