KeyStore.Builder (Java Platform SE 8 )
Keywords: java.security.KeyStore.Builder class
Date: 2026-04-17

compact1, compact2, compact3
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 and Description
    --- | ---
    `protected` | `Builder()` Construct a new Builder.

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and 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(KeyStore keyStore, KeyStore.ProtectionParameter protectionParameter)` Returns a new Builder that encapsulates the given KeyStore.
    `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.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### Builder

          protected Builder()

      Construct a new Builder.

  - ### Method Detail

    - #### 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 to 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(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

Submit a bug or feature
For further API reference and developer documentation, see Java SE Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.
Copyright © 1993, 2026, Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.