MasterKey.Builder

Artifact: androidx.security:security-crypto

View Source

Added in 1.1.0-alpha07

---

Kotlin |Java

class MasterKey.Builder

---

Builder for generating a MasterKey.

Summary

Public constructors
Builder(context: Context) Creates a builder for a MasterKey using the default alias of DEFAULT_MASTER_KEY_ALIAS.
Builder(context: Context, keyAlias: String) Creates a builder for a MasterKey.

Public functions
MasterKey	build() Builds a MasterKey from this builder.
MasterKey.Builder	@RequiresApi(value = Build.VERSION_CODES.M) setKeyGenParameterSpec(keyGenParameterSpec: KeyGenParameterSpec) Sets a custom KeyGenParameterSpec to use as the basis of the master key.
MasterKey.Builder	setKeyScheme(keyScheme: MasterKey.KeyScheme) Sets a KeyScheme to be used for the master key.
MasterKey.Builder	setRequestStrongBoxBacked(requestStrongBoxBacked: Boolean) Sets whether or not to request this key is strong box backed.
MasterKey.Builder	setUserAuthenticationRequired(authenticationRequired: Boolean) When used with setKeyScheme, 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(     authenticationRequired: Boolean,     userAuthenticationValidityDurationSeconds: @IntRange(from = 1) Int ) When used with setKeyScheme, 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.

Public constructors

Builder

Added in 1.1.0-alpha07

Builder(context: Context)

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

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

Builder

Added in 1.1.0-alpha07

Builder(context: Context, keyAlias: String)

Creates a builder for a MasterKey.

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

Public functions

build

Added in 1.1.0-alpha07

fun build(): MasterKey

Builds a MasterKey from this builder.

Returns
MasterKey	The master key.

Throws
java.security.GeneralSecurityException
java.io.IOException

setKeyGenParameterSpec

Added in 1.1.0-alpha07

@RequiresApi(value = Build.VERSION_CODES.M)
fun setKeyGenParameterSpec(keyGenParameterSpec: KeyGenParameterSpec): MasterKey.Builder

Sets a custom KeyGenParameterSpec to use as the basis of the master key. NOTE: Either this method OR setKeyScheme 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

Added in 1.1.0-alpha07

fun setKeyScheme(keyScheme: MasterKey.KeyScheme): MasterKey.Builder

Sets a KeyScheme to be used for the master key.

This uses a default KeyGenParameterSpec associated with the provided KeyScheme.

NOTE: Either this method OR setKeyGenParameterSpec 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

Added in 1.1.0-alpha07

fun setRequestStrongBoxBacked(requestStrongBoxBacked: Boolean): MasterKey.Builder

Sets whether or not to request this key is strong box backed. This setting is only applicable on 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

Added in 1.1.0-alpha07

fun setUserAuthenticationRequired(authenticationRequired: Boolean): MasterKey.Builder

When used with setKeyScheme, 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 getDefaultAuthenticationValidityDurationSeconds.

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

Returns
MasterKey.Builder	This builder.

setUserAuthenticationRequired

Added in 1.1.0-alpha07

fun setUserAuthenticationRequired(
    authenticationRequired: Boolean,
    userAuthenticationValidityDurationSeconds: @IntRange(from = 1) Int
): MasterKey.Builder

When used with setKeyScheme, 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: @IntRange(from = 1) Int	Duration in seconds that the key should remain unlocked following user authentication.

Returns
MasterKey.Builder	This builder.