com.ibm.di.security
Class CryptoFactory

java.lang.Object
  extended by com.ibm.di.security.CryptoFactory

public class CryptoFactory
extends 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
static 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 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
CryptoFactory()
           
 
Method Summary
static Cipher createCipher(String transformation, Provider cryptoProvider)
          A convenience method for instantiating a Cipher from a given security provider.
static Crypto createCrypto(KeyStore keyStore, String keyAlias, String keyPass, String transformation, Provider cryptoProvider)
           Creates an object that can encrypt/decrypt data using the specified cryptography transformation.
static Crypto createCrypto(String keyStorePath, String keyStorePass, String keyStoreType, String keyAlias, String keyPass, String transformation, Provider cryptoProvider)
           Creates an object that can encrypt/decrypt data using the specified cryptography transformation.
static KeyStore loadKeyStore(String keyStorePath, String keyStorePass, String keyStoreType)
          Loads a keystore into memory.
static Provider loadProvider(String providerClassName)
           
static KeyStore.Entry obtainEntry(KeyStore keyStore, String alias, 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 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 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(String keyStorePath,
                                  String keyStorePass,
                                  String keyStoreType,
                                  String keyAlias,
                                  String keyPass,
                                  String transformation,
                                  Provider cryptoProvider)
                           throws 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:
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(KeyStore keyStore,
                                  String keyAlias,
                                  String keyPass,
                                  String transformation,
                                  Provider cryptoProvider)
                           throws 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:
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 KeyStore loadKeyStore(String keyStorePath,
                                    String keyStorePass,
                                    String keyStoreType)
                             throws Exception
Loads a keystore into memory.

Parameters:
keyStorePath - keystore file path
keyStorePass - keystore password
keyStoreType - keystore type
Returns:
the keystore in-memory object
Throws:
Exception - problem while reading the keystore

obtainEntry

public static KeyStore.Entry obtainEntry(KeyStore keyStore,
                                         String alias,
                                         String pass)
                                  throws 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:
Exception - if the password for the entry is incorrect, or the entry is missing

createCipher

public static Cipher createCipher(String transformation,
                                  Provider cryptoProvider)
                           throws 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:
Exception - error, reported by the provider

loadProvider

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