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

Module java.base
Package java.security

# 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 ProtectionParameters 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 ProtectionParameters 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 ProtectionParameters 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 protectionParameters 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