Package org.forgerock.opendj.security

Class KeyManagers

  • public final class KeyManagers
extends Object
    This class contains methods for creating common types of key manager.

    • Method Detail

      • getSecurityProvider

        public static Provider getSecurityProvider​(String providerName,
                                           String providerClass,
                                           String providerArg)
                                    throws SecurityException
        Construct a Provider instance using either its name or its class name, and configure it.
        Parameters:
        providerName - the name of the provider or null
        providerClass - the name of the provider class or null
        providerArg - the name of the provider argument (often a path to a config file) or null
        Returns:
        the configured Provider
        Throws:
        SecurityException

      • useKeyStoreFile

        public static X509KeyManager useKeyStoreFile​(String file)
                                      throws GeneralSecurityException,
                                             IOException
        Creates a new X509KeyManager which will use the named key store file for retrieving certificates. It will use the default key store type for the JVM (e.g. PKCS12) and will not use a password to open the key store.
        Parameters:
        file - The key store file name.
        Returns:
        A new X509KeyManager which will use the named key store file for retrieving certificates.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store file could not be found or could not be read.
        NullPointerException - If provided file was null.

      • useKeyStoreFile

        public static X509KeyManager useKeyStoreFile​(String file,
                                             char[] password,
                                             String type)
                                      throws GeneralSecurityException,
                                             IOException
        Creates a new X509KeyManager which will use the named key store file for retrieving certificates. It will use the provided key store type and password.
        Parameters:
        file - The key store file name.
        password - The key store password, which may be null.
        type - The key store type, which may be null to indicate that the default key store type for the JVM (e.g. PKCS12) should be used.
        Returns:
        A new X509KeyManager which will use the named key store file for retrieving certificates.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store file could not be found or could not be read.
        NullPointerException - If file was null.

      • useKeyStoreFile

        public static X509KeyManager useKeyStoreFile​(String keyStoreFile,
                                             char[] password,
                                             String type,
                                             String providerName)
                                      throws GeneralSecurityException,
                                             IOException
        Creates a new X509KeyManager which will use the named key store file for retrieving certificates. It will use the provided key store type and password.
        Parameters:
        keyStoreFile - The key store file name.
        password - The key store password, which may be null.
        type - The key store type, which may be null to indicate that the default key store type for the JVM (e.g. PKCS12) should be used.
        providerName - The key store provider, which may be null to indicate that the default key store provider for the JVM should be used.
        Returns:
        A new X509KeyManager which will use the named key store file for retrieving certificates.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store file could not be found or could not be read.
        NullPointerException - If provided file was null.

      • usePkcs11Token

        public static X509KeyManager usePkcs11Token​(char[] password)
                                     throws GeneralSecurityException
        Creates a new X509KeyManager which will use a PKCS#11 token for retrieving certificates.
        Parameters:
        password - The password to use for accessing the PKCS#11 token, which may be null if no password is required.
        Returns:
        A new X509KeyManager which will use a PKCS#11 token for retrieving certificates.
        Throws:
        GeneralSecurityException - If the PKCS#11 token could not be accessed, perhaps due to incorrect password, or missing algorithms.

      • jvmDefaultKeyStore

        public static KeyStore jvmDefaultKeyStore()
                                   throws GeneralSecurityException,
                                          IOException
        Returns the JVM default keystore.
        Returns:
        The JVM default keystore or null if the necessary JVM settings are missing.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store file could not be found or could not be read.

      • useJvmDefaultKeyManager

        public static X509KeyManager useJvmDefaultKeyManager()
                                              throws GeneralSecurityException,
                                                     IOException
        Creates a new X509KeyManager which will use the JVM's default keystore for retrieving certificates.
        Returns:
        A new X509KeyManager which will use the JVM's default keystore for retrieving certificates or null if the necessary JVM settings are missing.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store file could not be found or could not be read.

      • useSingleCertificate

        public static X509KeyManager useSingleCertificate​(X509KeyManager keyManager,
                                                  String alias)
        Returns a new X509KeyManager which selects the named certificate from the provided key manager.
        Parameters:
        keyManager - The key manager to be filtered.
        alias - The alias of the certificate that should be selected for operations involving this key manager.
        Returns:
        The filtered key manager.
        Throws:
        NullPointerException - If provided keyManager or alias was null.

      • useAnyCertificate

        public static X509KeyManager useAnyCertificate​(X509KeyManager keyManager,
                                               String componentName,
                                               Collection<String> aliases)
        Returns a new X509KeyManager which selects one of the named certificates from the provided key manager.
        Parameters:
        keyManager - The key manager to be filtered.
        componentName - The optional user-friendly name of the component using the key manager. This will be used in error messages when the key manager fails to find a suitable certificate for the SSL handshake. May be null in which case the component name will be "unknown".
        aliases - The aliases of the certificates that can be selected for operations involving this key manager.
        Returns:
        The filtered key manager.
        Throws:
        NullPointerException - If provided keyManager or aliases was null or empty.

      • loadKeyStore

        public static KeyStore loadKeyStore​(String keyStorePath,
                                    char[] password,
                                    String keyStoreType)
                             throws GeneralSecurityException,
                                    IOException
        Loads and then returns a new key store object created with the provided path, password and type.

        The most preferred provider from the list of registered security provider will be used to create the KeyStore object.

        Parameters:
        keyStorePath - A string representing the path of the key store to create. It can be null, empty or set to NONE if the keystore should be load from an hardware token (associated key store type is PKCS11).
        password - The password to use for loading the key store, might be null if the key store has no password.
        keyStoreType - A string representing the type of the key store to load.
        Returns:
        A KeyStore already loaded which can be used for creating an X509KeyManager.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store should be loaded from a file which could not be found or could not be read.
        See Also:
        KeyStore.getInstance(String)

      • loadKeyStore

        public static KeyStore loadKeyStore​(String keyStoreType,
                                    char[] password,
                                    Provider provider)
                             throws LocalizedKeyStoreException
        Loads and then returns a new key store object created with the provided type, password and provider.
        Parameters:
        keyStoreType - A string representing the type of the key store to load.
        password - The password to use for loading the key store, might be null if the key store has no password.
        provider - The provider to use for loading the key store. Cannot be null.
        Returns:
        A KeyStore already loaded which can be used for creating an X509KeyManager.
        Throws:
        LocalizedKeyStoreException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms, or if the provider is not usable.
        See Also:
        KeyStore.getInstance(String, java.security.Provider)

      • loadKeyStore

        public static KeyStore loadKeyStore​(String keyStorePath,
                                    char[] password,
                                    String keyStoreType,
                                    Provider provider)
                             throws GeneralSecurityException,
                                    IOException
        Loads and then returns a new key store object created with the provided path, password, type and provider.
        Parameters:
        keyStorePath - A string representing the path of the key store to create. It can be null, empty or set to NONE if the keystore should be load from an hardware token (associated key store type is PKCS11).
        password - The password to use for loading the key store, might be null if the key store has no password.
        keyStoreType - A string representing the type of the key store to load.
        provider - The provider to use for loading the key store. Can be null, in which case the most appropriate provider from the list of registered security providers will be used.
        Returns:
        A KeyStore already loaded which can be used for creating an X509KeyManager.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store should be loaded from a file which could not be found or could not be read.
        See Also:
        KeyStore.getInstance(String), KeyStore.getInstance(String, java.security.Provider)

      • loadKeyStore

        public static KeyStore loadKeyStore​(Path keyStorePath,
                                    char[] password,
                                    String keyStoreType)
                             throws GeneralSecurityException,
                                    IOException
        Loads and then returns a new key store object created with the provided path, password and type.

        The most preferred provider from the list of registered security provider will be used to create the KeyStore object.

        Parameters:
        keyStorePath - The path of the key store to create. It can be null if the keystore should be load from an hardware token (associated key store type is PKCS11).
        password - The password to use for loading the key store, might be null if the key store has no password.
        keyStoreType - A string representing the type of the key store to load.
        Returns:
        A KeyStore already loaded which can be used for creating an X509KeyManager.
        Throws:
        GeneralSecurityException - If the key store could not be loaded, perhaps due to incorrect type, or missing algorithms.
        IOException - If the key store should be loaded from a file which could not be found or could not be read.
        See Also:
        KeyStore.getInstance(String), KeyStore.getInstance(String, java.security.Provider)

      • loadKeyStore

        public static KeyStore loadKeyStore​(String keyStoreType,
                                    char[] keyStorePin)
                             throws LocalizedKeyStoreException
        Loads a key store using the provided type and pin.
        Parameters:
        keyStoreType - the key store type to load
        keyStorePin - the pin to use when loading the key store, or null
        Returns:
        the loaded key store
        Throws:
        LocalizedKeyStoreException - When loading the key store fails, the thrown exception will have the cause attached. Possible causes if key store loading failed with an IOException: If there is an I/O or format problem with the keystore data, if a password is required but not given, or if the given password was incorrect. If the error is due to a wrong password, the cause of the IOException should be an UnrecoverableKeyException. Possible causes if key store loading failed with a GeneralSecurityException: If no Provider supports a KeyStoreSpi implementation for the specified type. If no provider supports a trust manager factory spi implementation for the specified algorithm. If any of the certificates in the key store could not be loaded.

      • loadKeyStore

        public static KeyStore loadKeyStore​(KeyStore keyStore,
                                    InputStream stream,
                                    char[] keyStorePin)
                             throws LocalizedKeyStoreException
        Loads a key store using the provided input stream and pin.
        Parameters:
        keyStore - the key store object where to load the actual key store
        stream - the input stream from which the keystore is loaded, or null
        keyStorePin - the pin to use when loading the key store, or null
        Returns:
        the provided key store
        Throws:
        LocalizedKeyStoreException - When loading the key store fails, the thrown exception will have the cause attached. Possible causes if key store loading failed with an IOException: If there is an I/O or format problem with the keystore data, if a password is required but not given, or if the given password was incorrect. If the error is due to a wrong password, the cause of the IOException should be an UnrecoverableKeyException. Possible causes if key store loading failed with a GeneralSecurityException: If no Provider supports a KeyStoreSpi implementation for the specified type. If no provider supports a trust manager factory spi implementation for the specified algorithm. If any of the certificates in the key store could not be loaded.

      • isPkcs11

        public static boolean isPkcs11​(String keyStorePath)
        Returns true if the PKCS#11 keystore type can be associated to the provided keystore path.

        This method considers that the PKCS#11 type can be inferred if either:

        • path is null
        • path is a blank string
        • path is set (case insensitive) to NONE (see documentation)
        Parameters:
        keyStorePath - The keystore path to test
        Returns:
        Returns true if the PKCS#11 keystore type can be associated to the provided keystore path