Initializer ("Entrust Authority Security Toolkit for the Java Platform")

java.lang.Object
- com.entrust.toolkit.security.provider.Initializer

```
public final class Initializer
extends java.lang.Object
```
Initializes the Toolkit to prepare for performing cryptographic operations.
Your application should retrieve an instance of an Initializer and invoke its setProviders() or setProviders(int) API before it performs cryptographic operations.
```
    // Example 1 -- use Normal mode
    Initializer.getInstance().setProviders(Initializer.MODE_NORMAL);
    
    // Example 2 -- use Entrust First mode
    Initializer.getInstance().setProviders(Initializer.MODE_ENTRUST_FIRST);
    
    // Example 3 -- use Entrust Last mode
    Initializer.getInstance().setProviders(Initializer.MODE_ENTRUST_LAST);
    
    // Example 4 -- use Static Initialization 
    Initializer.getInstance().setProviders(Initializer.MODE_STATIC);
    
    // Example 5 -- use the default mode of operation
    Initializer.getInstance().setProviders();
    
    // Example 6 -- FIPS operation (internally uses the default mode of operation)
    // com.entrust.toolkit.security.fips.SecurityEngine.initialize(true);
 
```
Initializing the Toolkit dynamically installs the JCA/JCE cryptographic service providers (CSP) that come with the Toolkit and are required when using the Toolkit's cryptographic functionality. This causes the Entrust and IAIK CSPs to be added to the list of approved providers. Depending on which mode is selected, the Entrust CSPs are installed with different preference (in different positions); for details, refer to the documentation for each pre-defined mode:
In addition to these pre-defined modes of operation, there is also a default mode of operation. This is the mode of operation that is used when a call to setProviders() is made. The default mode of operation is configured to 'MODE_ENTRUST_FIRST' mode; the Entrust and IAIK CSPs are installed with highest preference (in first and second positions). In versions of the toolkit prior to 8.1, the default mode of operation was 'MODE_NORMAL' model; the Entrust and IAIK CSPs are installed behind certain Sun and IBM CSPs. To set the default mode to 'MODE_NORMAL', set the following system property (at class loading time):
```
 com.entrust.toolkit.security.provider.Initializer.defaultMode=MODE_NORMAL
 
```
Some of the Toolkit's internal operations automatically initialize the Toolkit in the default mode of operation. For example, all CredentialReaders initialize the Toolkit in the default mode of operation when created. An application that performs cryptographic operations without utilizing those classes (typically, an application which does not log in) must set initialize the Toolkit itself (by manually invoking one of the setProviders() APIs).

Note:

To initialize the Toolkit in the FIPS 140 mode of operation use the SecurityEngine class; this requests that the JCA/JCE CSPs be installed using the default mode.
Since:

6.1

See Also:
SecurityEngine

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`MODE_ENTRUST_FIRST` Entrust First Mode: The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with highest preference (in first and second positions).
`static int`	`MODE_ENTRUST_LAST` Entrust Last Mode: The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with lowest preference (in second last and last positions).
`static int`	`MODE_NORMAL` Normal Mode: The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with intermediate preference (in the middle positions).
`static int`	`MODE_STATIC` Static Mode: The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed statically using the JVM's java.security file or dynamically by the application.
`static int`	`MODE_TOKEN` Deprecated. since 7.2 patch; use `MODE_NORMAL` instead
`static int`	`MODE_UNINITIALIZED` Uninitialized Mode: None of Entrust's JCA/JCE CSPs are installed.

Method Summary

Methods
Modifier and Type	Method and Description
`static void`	`assertVeryStrongCryptoAllowed()` Ensures that "very strong" cryptography is permitted by the jurisdiction policy files.
`static void`	`checkToolkitIntegrity()` Checks the integrity of the Toolkit.
`static Initializer`	`getInstance()` Returns the unique instance of the `Initializer`.
`int`	`getMode()` An accessor method that returns the mode in which the Toolkit is operating.
`static java.util.jar.JarFile[]`	`getToolkitCryptoJarFiles()` Retrieves all the Toolkit JAR files that contain classes that are part of the FIPS 140 cryptographic module (contain cryptographic algorithms).
`void`	`setProviders()` Dynamically installs the JCA/JCE cryptographic service providers (CSP) that come with the Toolkit and are required when using the Toolkit's cryptographic functionality.
`void`	`setProviders(int mode)` Dynamically installs the JCA/JCE cryptographic service providers (CSP) that come with the Toolkit and are required when using the Toolkit's cryptographic functionality.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail
- MODE_UNINITIALIZED
```
public static final int MODE_UNINITIALIZED
```
  Uninitialized Mode:
  
  None of Entrust's JCA/JCE CSPs are installed.
  
  See Also:
  Constant Field Values
- MODE_NORMAL
```
public static final int MODE_NORMAL
```
  Normal Mode:
  
  The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with intermediate preference (in the middle positions).
  
  The Entrust CSPs are installed immediately following certain SUN and IBM CSPs. The Entrust CSPs are installed behind all existing CSPs whose name meets any of the following criteria (case insensitive):
  - CSP name equals 'SUN'
  - CSP name contains 'SUN' and 'RSA'
  - CSP name contains 'IBM'
  This is done to workaround JRE bugs that prevent Entrust's CSPs from being installed with highest preference. Use this mode of operation when you do not have control over the environment (the JRE version) that your application will be used under, or you need to run under a JRE that is known to have these bugs (many 1.4.0 and 1.4.1 JREs). This mode offers a compromise; Entrust's CSPs are installed in the highest positions possible under all supported JREs.
  See Also:
  Constant Field Values
- MODE_TOKEN
```
public static final int MODE_TOKEN
```
  Deprecated. since 7.2 patch; use MODE_NORMAL instead
  
  Token Mode:
  
  The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with intermediate preference (in the middle positions).
  
  In previous releases, this mode was used to signify that private cryptographic operations are performed on a Cryptoki Token device (PKCS #11), but is now identical to MODE_NORMAL.
  
  See Also:
  Constant Field Values
- MODE_ENTRUST_FIRST
```
public static final int MODE_ENTRUST_FIRST
```
  Entrust First Mode:
  
  The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with highest preference (in first and second positions).
  
  Use this mode when you want to ensure that Entrust cryptographic algorithms are used automatically in code that respects the JCA/JCE CSP installation order.
  
  Since:
  
  7.2 patch
  
  See Also:
  Constant Field Values
- MODE_ENTRUST_LAST
```
public static final int MODE_ENTRUST_LAST
```
  Entrust Last Mode:
  
  The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed with lowest preference (in second last and last positions).
  
  Since:
  
  7.2 patch
  
  See Also:
  Constant Field Values
- MODE_STATIC
```
public static final int MODE_STATIC
```
  Static Mode:
  
  The 'Entrust' and 'IAIK' JCA/JCE CSPs are installed statically using the JVM's java.security file or dynamically by the application.
  Note: Setting this mode will not remove or order the providers in any way. This mode therefore expects the toolkit user to have installed the providers either statically through the java.security file or dynamically in the application via Security.addProvider(). If this mode is used and the application has not set the providers, then the providers will not be installed and trying to access a cryptographic algorithm from the Entrust or IAIK providers will result in a NoSuchProviderException. Therefore, using this setting gives control of provider ordering to the application user.
  
  Since:
  
  8.0 patch
  
  See Also:
  Constant Field Values

Method Detail

getInstance
```
public static Initializer getInstance()
```
Returns the unique instance of the Initializer.

Returns:
A reference to the Initializer.

setProviders
```
public void setProviders(int mode)
```
Dynamically installs the JCA/JCE cryptographic service providers (CSP) that come with the Toolkit and are required when using the Toolkit's cryptographic functionality.
If the Toolkit is already operating in the specified mode, the invocation does nothing. After this call, you should determine whether the desired mode was set successfully by calling getMode(). The supported modes are:
Usually, a multi-threaded application will need to initialize only once. In any case, CSPs are shared between threads, so your application should not permit a thread to change the mode of operation while another thread is performing cryptographic operations.

A reset to MODE_UNINITIALIZED removes the Toolkit's CSPs, which typically leaves only the Java's default CSPs available.

The first time the Toolkit is initialized in to any mode that installs Entrust's CSPs, the entropy gathering routine is started. This is done in a separate thread, however, any attempt to use a random number generator before this process completes will block until it does complete. This may take a few seconds, depending on the system.

Applications That Require Very Strong Cryptography

If the com.entrust.toolkit.security.provider.Initializer.requireVeryStrongCrypto system property is set, when initializing in any mode that installs Entrust's CSPs, this call will also ensure that "very strong" cryptography is permitted by calling assertVeryStrongCryptoAllowed(). For applications that require very strong cryptography (256-bit AES, 4096-bit RSA...), this will ensure that the environment is configured to allow these algorithms, otherwise a VeryStrongCryptoNotPermittedException will be thrown.

Note:

To initialize the Toolkit in the FIPS 140 mode of operation use the SecurityEngine class; this requests that the JCA/JCE CSPs be installed using the default mode.
Parameters:
mode - is the mode to be set
See Also:
getMode(), SecurityEngine.initialize(boolean fipsMode)

setProviders
```
public void setProviders()
```
Dynamically installs the JCA/JCE cryptographic service providers (CSP) that come with the Toolkit and are required when using the Toolkit's cryptographic functionality.
This call simply initializes the Toolkit in the default mode of operation. The default mode of operation may be configured to any of the following pre-defined modes of operation:
By default, the default mode of operation is set to 'MODE_ENTRUST_FIRST' mode. However, the default mode of operation can be configured using the following system property (at class loading time):
```
 com.entrust.toolkit.security.provider.Initializer.defaultMode=MODE_NORMAL
 com.entrust.toolkit.security.provider.Initializer.defaultMode=MODE_ENTRUST_FIRST
 com.entrust.toolkit.security.provider.Initializer.defaultMode=MODE_ENTRUST_LAST
 com.entrust.toolkit.security.provider.Initializer.defaultMode=MODE_STATIC
 
```
The default mode of operation is the mode that the Toolkit uses any time it initialize itself. This happens in several places (at FIPS 140 initialization, inside the constructor of any credential reader ...).

The default mode of operation is configured to 'MODE_ENTRUST_FIRST' mode; the Entrust and IAIK CSPs are installed with highest preference (in first and second positions). In versions of the toolkit prior to 8.1, the default mode of operation was 'MODE_NORMAL' model; the Entrust and IAIK CSPs are installed behind certain Sun and IBM CSPs. To set the default mode to 'MODE_NORMAL', set the following system property:
```
 com.entrust.toolkit.security.provider.Initializer.defaultMode=MODE_NORMAL
 
```
Since:

7.1 Patch

getMode
```
public int getMode()
```
An accessor method that returns the mode in which the Toolkit is operating.
The supported modes are:
Returns:
an int that represents the mode

checkToolkitIntegrity
```
public static void checkToolkitIntegrity()
```
Checks the integrity of the Toolkit.
This is done by verifying the digital signatures on each Toolkit JAR file that contains cryptographic algorithm implementations. This ensures that the Toolkit JAR files have not been modified since being built by Entrust. This check is automatically run the first time either the 'Entrust' or 'IAIK' JCA cryptographic service providers are installed. The integrity check is only done once; once completed, subsequent calls to this API simply exit without running the check.

Note:

This call is used internally by the Toolkit; It should not be called externally.

getToolkitCryptoJarFiles
```
public static java.util.jar.JarFile[] getToolkitCryptoJarFiles()
```
Retrieves all the Toolkit JAR files that contain classes that are part of the FIPS 140 cryptographic module (contain cryptographic algorithms).
The purpose of this API is to provide access to the Toolkit JAR files so that their integrity can be checked.

Note:

This call is used internally by the Toolkit; It should not be called externally.

Returns:
the Toolkit JAR files

Throws:

java.lang.SecurityException - if the Toolkit JAR files could not be located or required JAR files are missing

assertVeryStrongCryptoAllowed

public static void assertVeryStrongCryptoAllowed()

Ensures that "very strong" cryptography is permitted by the jurisdiction policy files.

Applications that require "very strong" or unlimited strength cryptography should call this API immediately following setProviders() or set the com.entrust.toolkit.security.provider.Initializer.requireVeryStrongCrypto system property (which causes this check to happen automatically during a call to setProviders()). This will ensure that the proper jurisdiction policy files are installed.

This call performs a check to ensure that "very strong" cryptography is permitted (all Entrust cipher algorithm implementations are permitted with keys of large size). Due to export control restriction (to certain countries), the JCE enforces cryptographic algorithm restrictions on cipher algorithms. These restrictions are controlled by jurisdiction policy files. By default, J2SE comes with policy files that permit "strong" but limited cryptography to be used. But, "unlimited strength" versions of these files can be installed by those living in countries that do not fall under cryptography export restrictions; these files impose no restrictions.

Entrust recommends that the Toolkit be used in environments in which the "unlimited strength" jurisdiction policy files have been installed. The Toolkit internally uses "very strong" cipher algorithms for various purposes. When the "unlimited strength" policy files are not present, certain Toolkit functionality will not be permitted by the JCE because it violates these cryptographic restrictions. Attempting to use this functionality will result in a java.security.InvalidKeyException or java.lang.SecurityException.

Based on the Java permissions architecture, it is not possible to programmatically determine whether the CryptoAllPermission permission is present or not (this would indicate unlimited strength cryptography is available). So instead, a manual test of each Entrust cipher algorithm is done with a key of sufficient size to be considered "very strong". The following algorithms are tested with the indicated key strengths:

Very Strong Cryptography (as defined by Entrust)

Cipher Algorithms
Algorithm Name	Strength (bits)
AES	256
AES key wrap	256
CAST128	128
CAST3	64
DES	56
DESede	168
Elgamal	2048
IDEA	128
RC2	256
RC4	256
Rijndael	256
Rijndael-256	256
RSA	4096

For comparison, Java's "strong" cryptography includes the following algorithms with the indicated key strengths:

Strong Cryptography (as defined in J2SE 1.4 and 1.5)

Cipher Algorithms
Algorithm Name	Strength (bits)
DES	56
DESede	unlimited
RC2	128
RC4	128
RC5	128
RSA	2048
All others	128

Throws:: VeryStrongCryptoNotPermittedException - if "very strong" cryptography is not permitted; EntrustProviderMissingException - if the Entrust CSP has not been installed; EntrustProviderTamperedException - if the Entrust CSP has been tampered
Since:: 7.2

Class Initializer

Field Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MODE_UNINITIALIZED

MODE_NORMAL

MODE_TOKEN

MODE_ENTRUST_FIRST

MODE_ENTRUST_LAST

MODE_STATIC

Method Detail

getInstance

setProviders

setProviders

getMode

checkToolkitIntegrity

getToolkitCryptoJarFiles

assertVeryStrongCryptoAllowed