KeyStore.Builder (Java SE 23 & JDK 23)
Description: declaration: module: java.base, package: java.security, class: KeyStore, class: Builder
Keywords: java.security.KeyStore.Builder class

# Class KeyStore.Builder

java.lang.Object
java.security.KeyStore.Builder

Enclosing class:
  `KeyStore`

public abstract static class KeyStore.Builder extends Object
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() 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.

Since:
  1.5
See Also:
  - `KeyStore`
  - `KeyStoreBuilderParameters`

- ## Constructor Summary

  Constructors
  Modifier
  Constructor
  Description
  `protected`
  `Builder()`
  Construct a new `Builder`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract KeyStore`
  `getKeyStore()`
  Returns the `KeyStore` described by this object.
  `abstract KeyStore.ProtectionParameter`
  `getProtectionParameter(String alias)`
  Returns the `ProtectionParameter` that should be used to obtain the `Entry` with the given alias.
  `static KeyStore.Builder`
  `newInstance(File file, KeyStore.ProtectionParameter protection)`
  Returns a new `Builder` object.
  `static KeyStore.Builder`
  `newInstance(String type, Provider provider, File file, KeyStore.ProtectionParameter protection)`
  Returns a new `Builder` object.
  `static KeyStore.Builder`
  `newInstance(String type, Provider provider, KeyStore.ProtectionParameter protection)`
  Returns a new `Builder` object.
  `static KeyStore.Builder`
  `newInstance(KeyStore keyStore, KeyStore.ProtectionParameter protectionParameter)`
  Returns a new `Builder` that encapsulates the given `KeyStore`.

  ### Methods declared in class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Constructor Details

  - ### Builder

    protected Builder()
    Construct a new `Builder`.

- ## Method Details

  - ### getKeyStore

    public abstract KeyStore getKeyStore() throws KeyStoreException
    Returns the `KeyStore` described by this object.
    Returns:
      the `KeyStore` described by this object
    Throws:
      `KeyStoreException` - if an error occurred during the operation, for example if the `KeyStore` could not be instantiated or loaded

  - ### getProtectionParameter

    public abstract KeyStore.ProtectionParameter getProtectionParameter(String alias) throws KeyStoreException
    Returns the `ProtectionParameter` that should be used to obtain the `Entry` with the given alias. The `getKeyStore` method must be invoked before this method may be called.
    Parameters:
      `alias` - the alias of the `KeyStore` entry
    Returns:
      the `ProtectionParameter` that should be used to obtain the `Entry` with the given alias.
    Throws:
      `NullPointerException` - if alias is `null`
      `KeyStoreException` - if an error occurred during the operation
      `IllegalStateException` - if the `getKeyStore` method has not been invoked prior to calling this method

  - ### newInstance

    public static KeyStore.Builder newInstance(KeyStore keyStore, KeyStore.ProtectionParameter protectionParameter)
    Returns a new `Builder` that encapsulates the given `KeyStore`. The getKeyStore() method of the returned object will return `keyStore`, the getProtectionParameter() method will return `protectionParameters`.

    This is useful if an existing `KeyStore` object needs to be used with builder-based APIs.

    Parameters:
      `keyStore` - the `KeyStore` to be encapsulated
      `protectionParameter` - the `ProtectionParameter` used to protect the `KeyStore` entries
    Returns:
      a new `Builder` object
    Throws:
      `NullPointerException` - if `keyStore` or `protectionParameter` is `null`
      `IllegalArgumentException` - if the `keyStore` has not been initialized

  - ### newInstance

    public static KeyStore.Builder newInstance(String type, Provider provider, File file, KeyStore.ProtectionParameter protection)
    Returns a new `Builder` object.

    The first call to the `getKeyStore()` method on the returned builder will create a `KeyStore` of type `type` and call its `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()` 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()` will return a `PasswordProtection` object encapsulating the password that was used to invoke the `load` method.

    Note that the `getKeyStore()` method is executed within the `AccessControlContext` of the code invoking this method.

    Parameters:
      `type` - the type of `KeyStore` to be constructed
      `provider` - the provider from which the `KeyStore` is to be instantiated (or `null`)
      `file` - the File that contains the `KeyStore` data
      `protection` - the `ProtectionParameter` securing the `KeyStore` data
    Returns:
      a new `Builder` object
    Throws:
      `NullPointerException` - if type, file or protection is `null`
      `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

    public static KeyStore.Builder newInstance(File file, KeyStore.ProtectionParameter protection)
    Returns a new `Builder` object.

    The first call to the `getKeyStore()` method on the returned builder will create a `KeyStore` using `file` to detect the keystore type and then call its `load()` method. It uses the same algorithm to determine the keystore type as described in `KeyStore.getInstance(File, 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()` 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()` will return a `PasswordProtection` object encapsulating the password that was used to invoke the `load` method.

    Note that the `getKeyStore()` method is executed within the `AccessControlContext` of the code invoking this method.

    Parameters:
      `file` - the File that contains the `KeyStore` data
      `protection` - the `ProtectionParameter` securing the `KeyStore` data
    Returns:
      a new `Builder` object
    Throws:
      `NullPointerException` - if file or protection is `null`
      `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
    Since:
      9

  - ### newInstance

    public static KeyStore.Builder newInstance(String type, Provider provider, KeyStore.ProtectionParameter protection)
    Returns a new `Builder` object.

    Each call to the `getKeyStore()` method on the returned builder will return a new `KeyStore` object of type `type`. Its `load()` 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()` will return `protection`.

    Note that the `getKeyStore()` method is executed within the `AccessControlContext` of the code invoking this method.

    Parameters:
      `type` - the type of `KeyStore` to be constructed
      `provider` - the provider from which the `KeyStore` is to be instantiated (or `null`)
      `protection` - the `ProtectionParameter` securing the `Keystore`
    Returns:
      a new `Builder` object
    Throws:
      `NullPointerException` - if type or protection is `null`