# KeyStore.Builder Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) # Builder ``` abstract class Builder ``` |---|------------------------------------------------------------------------------------------------------------------| | [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) || | ↳ | [java.security.KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#) | A description of a to-be-instantiated KeyStore object. An instance of this class encapsulates the information needed to instantiate and initialize a KeyStore object. That process is triggered when the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method is called. This makes it possible to decouple configuration from KeyStore object creation and e.g. delay a password prompt until it is needed. ## Summary | Protected constructors || |---------------------------------------------------------------------------------------------------------------------------------|---| | [Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#Builder())`()` Construct a new Builder. | | Public methods || |------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | abstract[KeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore)! | [getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())`()` Returns the KeyStore described by this object. | | abstract[KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)! | [getProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getProtectionParameter(kotlin.String))`(`alias:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!`)` Returns the ProtectionParameters that should be used to obtain the[Entry](https://developer.android.com/reference/kotlin/java/security/KeyStore.Entry)with the given alias. | | openstatic[KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | [newInstance](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#newInstance(java.io.File,%20java.security.KeyStore.ProtectionParameter))`(`file:` `[File](https://developer.android.com/reference/kotlin/java/io/File.html#)!`, `protection:` `[KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!`)` Returns a new Builder object. | | openstatic[KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | [newInstance](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#newInstance(kotlin.String,%20java.security.Provider,%20java.io.File,%20java.security.KeyStore.ProtectionParameter))`(`type:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!`, `provider:` `[Provider](https://developer.android.com/reference/kotlin/java/security/Provider)!`, `file:` `[File](https://developer.android.com/reference/kotlin/java/io/File.html#)!`, `protection:` `[KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!`)` Returns a new Builder object. | | openstatic[KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | [newInstance](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#newInstance(kotlin.String,%20java.security.Provider,%20java.security.KeyStore.ProtectionParameter))`(`type:` `[String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!`, `provider:` `[Provider](https://developer.android.com/reference/kotlin/java/security/Provider)!`, `protection:` `[KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!`)` Returns a new Builder object. | | openstatic[KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | [newInstance](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#newInstance(java.security.KeyStore,%20java.security.KeyStore.ProtectionParameter))`(`keyStore:` `[KeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore)!`, `protectionParameter:` `[KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!`)` Returns a new Builder that encapsulates the given KeyStore. | ## Protected constructors ### Builder Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` protected Builder() ``` Construct a new Builder. ## Public methods ### getKeyStore Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` abstract fun getKeyStore(): KeyStore! ``` Returns the KeyStore described by this object. | Return || |------------------------------------------------------------------------------------|---------------------------------------| | [KeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore)! | the`KeyStore`described by this object | | Exceptions || |-----------------------------------|------------------------------------------------------------------------------------------------------------| | `java.security.KeyStoreException` | if an error occurred during the operation, for example if the KeyStore could not be instantiated or loaded | ### getProtectionParameter Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` abstract fun getProtectionParameter(alias: String!): KeyStore.ProtectionParameter! ``` Returns the ProtectionParameters that should be used to obtain the[Entry](https://developer.android.com/reference/kotlin/java/security/KeyStore.Entry)with the given alias. The`getKeyStore`method must be invoked before this method may be called. | Parameters || |---------|-------------------------------------------------------------------------------------------------------------------| | `alias` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!:the alias of the KeyStore entry | | Return || |----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------| | [KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)! | the ProtectionParameters that should be used to obtain the[Entry](https://developer.android.com/reference/kotlin/java/security/KeyStore.Entry)with the given alias. | | Exceptions || |-----------------------------------|-----------------------------------------------------------------------------| | `java.lang.NullPointerException` | if alias is null | | `java.security.KeyStoreException` | if an error occurred during the operation | | `java.lang.IllegalStateException` | if the getKeyStore method has not been invoked prior to calling this method | ### newInstance Added in[API level 33](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` open static fun newInstance(     file: File!,     protection: KeyStore.ProtectionParameter! ): KeyStore.Builder! ``` Returns a new Builder object. The first call to the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method on the returned builder will create a KeyStore using`file`to detect the keystore type and then call its java.security.KeyStore#load method. It uses the same algorithm to determine the keystore type as described in[KeyStore.getInstance(File, LoadStoreParameter)](https://developer.android.com/reference/kotlin/java/security/KeyStore#getInstance(java.io.File,%20java.security.KeyStore.LoadStoreParameter)). The`inputStream`argument is constructed from`file`. If`protection`is a`PasswordProtection`, the password is obtained by calling the`getPassword`method. Otherwise, if`protection`is a`CallbackHandlerProtection`, the password is obtained by invoking the CallbackHandler. Subsequent calls to[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())return the same object as the initial call. If the initial call failed with a KeyStoreException, subsequent calls also throw a KeyStoreException. Calls to[getProtectionParameter()](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getProtectionParameter(kotlin.String))will return a[PasswordProtection](https://developer.android.com/reference/kotlin/java/security/KeyStore.PasswordProtection)object encapsulating the password that was used to invoke the`load`method. *Note* that the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method is executed within the[AccessControlContext](https://developer.android.com/reference/kotlin/java/security/AccessControlContext)of the code invoking this method. | Parameters || |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `file` | [File](https://developer.android.com/reference/kotlin/java/io/File.html#)!:the File that contains the KeyStore data | | `protection` | [KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!:the ProtectionParameter securing the KeyStore data | | Return || |-----------------------------------------------------------------------------------------------------|----------------------| | [KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | a new Builder object | | Exceptions || |--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | `java.lang.NullPointerException` | if file or protection is null | | `java.lang.IllegalArgumentException` | if protection is not an instance of either PasswordProtection or CallbackHandlerProtection; or if file does not exist or does not refer to a normal file | ### newInstance Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` open static fun newInstance(     type: String!,     provider: Provider!,     file: File!,     protection: KeyStore.ProtectionParameter! ): KeyStore.Builder! ``` Returns a new Builder object. The first call to the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method on the returned builder will create a KeyStore of type`type`and call its java.security.KeyStore#load method. The`inputStream`argument is constructed from`file`. If`protection`is a`PasswordProtection`, the password is obtained by calling the`getPassword`method. Otherwise, if`protection`is a`CallbackHandlerProtection`, the password is obtained by invoking the CallbackHandler. Subsequent calls to[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())return the same object as the initial call. If the initial call failed with a KeyStoreException, subsequent calls also throw a KeyStoreException. The KeyStore is instantiated from`provider`if non-null. Otherwise, all installed providers are searched. Calls to[getProtectionParameter()](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getProtectionParameter(kotlin.String))will return a[PasswordProtection](https://developer.android.com/reference/kotlin/java/security/KeyStore.PasswordProtection)object encapsulating the password that was used to invoke the`load`method. *Note* that the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method is executed within the[AccessControlContext](https://developer.android.com/reference/kotlin/java/security/AccessControlContext)of the code invoking this method. | Parameters || |--------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!:the type of KeyStore to be constructed | | `provider` | [Provider](https://developer.android.com/reference/kotlin/java/security/Provider)!:the provider from which the KeyStore is to be instantiated (or null) | | `file` | [File](https://developer.android.com/reference/kotlin/java/io/File.html#)!:the File that contains the KeyStore data | | `protection` | [KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!:the ProtectionParameter securing the KeyStore data | | Return || |-----------------------------------------------------------------------------------------------------|----------------------| | [KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | a new Builder object | | Exceptions || |--------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| | `java.lang.NullPointerException` | if type, file or protection is null | | `java.lang.IllegalArgumentException` | if protection is not an instance of either PasswordProtection or CallbackHandlerProtection; or if file does not exist or does not refer to a normal file | ### newInstance Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` open static fun newInstance(     type: String!,     provider: Provider!,     protection: KeyStore.ProtectionParameter! ): KeyStore.Builder! ``` Returns a new Builder object. Each call to the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method on the returned builder will return a new KeyStore object of type`type`. Its[load()](https://developer.android.com/reference/kotlin/java/security/KeyStore#load(java.security.KeyStore.LoadStoreParameter))method is invoked using a`LoadStoreParameter`that encapsulates`protection`. The KeyStore is instantiated from`provider`if non-null. Otherwise, all installed providers are searched. Calls to[getProtectionParameter()](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getProtectionParameter(kotlin.String))will return`protection`. *Note* that the[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method is executed within the[AccessControlContext](https://developer.android.com/reference/kotlin/java/security/AccessControlContext)of the code invoking this method. | Parameters || |--------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `type` | [String](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-string/index.html)!:the type of KeyStore to be constructed | | `provider` | [Provider](https://developer.android.com/reference/kotlin/java/security/Provider)!:the provider from which the KeyStore is to be instantiated (or null) | | `protection` | [KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!:the ProtectionParameter securing the Keystore | | Return || |-----------------------------------------------------------------------------------------------------|----------------------| | [KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | a new Builder object | | Exceptions || |----------------------------------|-------------------------------| | `java.lang.NullPointerException` | if type or protection is null | ### newInstance Added in[API level 1](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) ``` open static fun newInstance(     keyStore: KeyStore!,     protectionParameter: KeyStore.ProtectionParameter! ): KeyStore.Builder! ``` Returns a new Builder that encapsulates the given KeyStore. The[getKeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getKeyStore())method of the returned object will return`keyStore`, the[getProtectionParameter()](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#getProtectionParameter(kotlin.String))method will return`protectionParameters`. This is useful if an existing KeyStore object needs to be used with Builder-based APIs. | Parameters || |-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `keyStore` | [KeyStore](https://developer.android.com/reference/kotlin/java/security/KeyStore)!:the KeyStore to be encapsulated | | `protectionParameter` | [KeyStore.ProtectionParameter](https://developer.android.com/reference/kotlin/java/security/KeyStore.ProtectionParameter)!:the ProtectionParameter used to protect the KeyStore entries | | Return || |-----------------------------------------------------------------------------------------------------|----------------------| | [KeyStore.Builder](https://developer.android.com/reference/kotlin/java/security/KeyStore.Builder#)! | a new Builder object | | Exceptions || |--------------------------------------|---------------------------------------------| | `java.lang.NullPointerException` | if keyStore or protectionParameters is null | | `java.lang.IllegalArgumentException` | if the keyStore has not been initialized |