Package com.ibm.di.security

Class CryptoFactory

  • public class CryptoFactory
extends java.lang.Object
    This factory creates objects, which can be used for encryption/decryption of data. The purpose of this class is to shield other code from dealing with keys and keystores and knowing concrete Crypto implementations.
    Since:
    7.0

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static java.lang.String CRYPTO_PROVIDER_CLASS_PROPERTY
      This system property specifies the Java class of a the default security provider that will be used for encryption/decryption.
      static java.lang.String CRYPTO_PROVIDER_NAME_PROPERTY
      This system property sets the name of a registered Java security provider that will be used as the default provider for encryption/decryption.

    • Constructor Summary

      Constructors 
      Constructor Description
      CryptoFactory()  

    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static javax.crypto.Cipher createCipher​(java.lang.String transformation, java.security.Provider cryptoProvider)
      A convenience method for instantiating a Cipher from a given security provider.
      static Crypto createCrypto​(java.lang.String keyStorePath, java.lang.String keyStorePass, java.lang.String keyStoreType, java.lang.String keyAlias, java.lang.String keyPass, java.lang.String transformation, java.security.Provider cryptoProvider)
      Creates an object that can encrypt/decrypt data using the specified cryptography transformation.
      static Crypto createCrypto​(java.security.KeyStore keyStore, java.lang.String keyAlias, java.lang.String keyPass, java.lang.String transformation, java.security.Provider cryptoProvider)
      Creates an object that can encrypt/decrypt data using the specified cryptography transformation.
      static java.security.KeyStore loadKeyStore​(java.lang.String keyStorePath, java.lang.String keyStorePass, java.lang.String keyStoreType)
      Loads a keystore into memory.
      static java.security.Provider loadProvider​(java.lang.String providerClassName)  
      static java.security.KeyStore.Entry obtainEntry​(java.security.KeyStore keyStore, java.lang.String alias, java.lang.String pass)
      Obtain an entry from a keystore.

      • Methods inherited from class java.lang.Object

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

    • Field Detail

      • CRYPTO_PROVIDER_CLASS_PROPERTY

        public static final java.lang.String CRYPTO_PROVIDER_CLASS_PROPERTY

        This system property specifies the Java class of a the default security provider that will be used for encryption/decryption. This provider will NOT be used for keystore management. The property is optional - if it is missing the default security provider list of the JRE will be used.

        This property must be interpreted by the application (e.g. the Server) on initialization. The specified provider class has to be instantiated and registered in the default security provider list of the JRE (e.g. using Security.addProvider(Provider)). Moreover the CRYPTO_PROVIDER_NAME_PROPERTY needs to be set to the name of the provider, so that other security classes can take advantage of it via the createCipher(String, Provider) method. Note that it is better for the large part of the code to access the provider by name from the default provider list rather than instantiate it every time because instantiation may be heavy-weight, may require security permissions or may require a specific class loader (e.g. the system class loader).

        See Also:
        Constant Field Values

      • CRYPTO_PROVIDER_NAME_PROPERTY

        public static final java.lang.String CRYPTO_PROVIDER_NAME_PROPERTY

        This system property sets the name of a registered Java security provider that will be used as the default provider for encryption/decryption. This provider will NOT be used for keystore management. The property is optional - if it is missing the default security provider list of the JRE will be used.

        This property is dependent on the value of the CRYPTO_PROVIDER_CLASS_PROPERTY property. Whenever you set the CRYPTO_PROVIDER_CLASS_PROPERTY property, you should update this property too.

        See Also:
        Constant Field Values

    • Constructor Detail

      • CryptoFactory

        public CryptoFactory()

    • Method Detail

      • createCrypto

        public static Crypto createCrypto​(java.lang.String keyStorePath,
                                  java.lang.String keyStorePass,
                                  java.lang.String keyStoreType,
                                  java.lang.String keyAlias,
                                  java.lang.String keyPass,
                                  java.lang.String transformation,
                                  java.security.Provider cryptoProvider)
                           throws java.lang.Exception

        Creates an object that can encrypt/decrypt data using the specified cryptography transformation.

        The transformation can be either "RSA" or some secret key transformation, which a call to javax.crypto.Cipher.getInstance would accept. For example "AES/CBC/PKCS5Padding". The transformation must explicitly require a secret key. Password-based (PBE) transformations are not supported by this method.

        If the transformation is set to "RSA", the specified keystore must contain a private key entry under the specified key alias. If the transformation involves a secret key cipher, the keystore must contain a secret key for that cipher under the key alias.

        The returned object will be thread-safe.

        Parameters:
        keyStorePath - a keystore file, which contains the key for encryption/decryption
        keyStorePass - the password of the keystore file
        keyStoreType - the type of the keystore file
        keyAlias - the alias of the key
        keyPass - the password of the key
        transformation - the name of the cryptography transformation
        cryptoProvider - a Java security provider that will be used for encryption/decryption; this provider will not be used for reading keystores; the provider does not have to be registered in the JRE; the parameter is optional - if it is set to null, the value of the "com.ibm.di.cryptoProviderName" system property will be used, if it is missing the default provider list for the JRE will be used
        Returns:
        an object that implements the specified cryptography transformation
        Throws:
        java.lang.Exception - If the transformation is "RSA" and the keystore does not contain a public/private key pair under the specified alias or if the keys are not suited for RSA. If the transformation involves a secret key cipher and the keystore does not contain a secret key under the specified alias.

      • createCrypto

        public static Crypto createCrypto​(java.security.KeyStore keyStore,
                                  java.lang.String keyAlias,
                                  java.lang.String keyPass,
                                  java.lang.String transformation,
                                  java.security.Provider cryptoProvider)
                           throws java.lang.Exception

        Creates an object that can encrypt/decrypt data using the specified cryptography transformation.

        The transformation can be either "RSA" or some secret key transformation, which a call to javax.crypto.Cipher.getInstance would accept. For example "AES/CBC/PKCS5Padding". The transformation must explicitly require a secret key. Password-based (PBE) transformations are not supported by this method.

        If the transformation is set to "RSA", the specified keystore must contain a private key entry under the specified key alias. If the transformation involves a secret key cipher, the keystore must contain a secret key for that cipher under the key alias.

        The returned object will be thread-safe.

        Parameters:
        keyStore - the KeyStore to use
        keyStorePath - path for the keystore file that was used to construct the KeyStore
        keyAlias - the alias of the key
        keyPass - the password of the key
        transformation - the name of the cryptography transformation
        cryptoProvider - a Java security provider that will be used for encryption/decryption; this provider will not be used for reading keystores; the provider does not have to be registered in the JRE; the parameter is optional - if it is set to null, the value of the "com.ibm.di.cryptoProviderName" system property will be used, if it is missing the default provider list for the JRE will be used
        Returns:
        an object that implements the specified cryptography transformation
        Throws:
        java.lang.Exception - If the transformation is "RSA" and the keystore does not contain a public/private key pair under the specified alias or if the keys are not suited for RSA. If the transformation involves a secret key cipher and the keystore does not contain a secret key under the specified alias.
        Since:
        7.1

      • loadKeyStore

        public static java.security.KeyStore loadKeyStore​(java.lang.String keyStorePath,
                                                  java.lang.String keyStorePass,
                                                  java.lang.String keyStoreType)
                                           throws java.lang.Exception
        Loads a keystore into memory.
        Parameters:
        keyStorePath - keystore file path
        keyStorePass - keystore password
        keyStoreType - keystore type
        Returns:
        the keystore in-memory object
        Throws:
        java.lang.Exception - problem while reading the keystore

      • obtainEntry

        public static java.security.KeyStore.Entry obtainEntry​(java.security.KeyStore keyStore,
                                                       java.lang.String alias,
                                                       java.lang.String pass)
                                                throws java.lang.Exception
        Obtain an entry from a keystore. (Provides a user friendly message when the password for the entry is wrong.)
        Parameters:
        keyStore - initialized keystore object
        alias - the entry in the keystore to obtain
        pass - password for the entry
        Returns:
        the obtained entry
        Throws:
        java.lang.Exception - if the password for the entry is incorrect, or the entry is missing

      • createCipher

        public static javax.crypto.Cipher createCipher​(java.lang.String transformation,
                                               java.security.Provider cryptoProvider)
                                        throws java.lang.Exception
        A convenience method for instantiating a Cipher from a given security provider. If null is specified for the provider, the CRYPTO_PROVIDER_NAME_PROPERTY property will be searched for the name of an already registered provider. If the property is empty or refers to a non-registered provider, the returned Cipher will rely on the list of security providers for the JRE.
        Parameters:
        transformation - a transformation valid for javax.crypto.Cipher.getInstance
        cryptoProvider - Java security provider, which supports the specified transformation
        Returns:
        the created Cipher
        Throws:
        java.lang.Exception - error, reported by the provider

      • loadProvider

        public static java.security.Provider loadProvider​(java.lang.String providerClassName)
                                           throws java.lang.Exception
        Parameters:
        providerClassName - Fully qualified Java class name of the security provider.
        Returns:
        An instance of the provider.
        Throws:
        java.lang.Exception - If the provider class cannot be found of the provider cannot be instantiated.