com.entrust.toolkit.security.fips

Class SecurityEngine

java.lang.Object

com.entrust.toolkit.security.fips.SecurityEngine

public abstract class SecurityEngine
extends java.lang.Object

This class is used to initialize the Toolkit in FIPS or non-FIPS mode.

To operate in FIPS mode the cryptographic module must be authenticated, and every cryptographic algorithm must be tested. This means that every JAR file that contains classes which belong to the cryptographic module must present. The JAR files which contain classes belonging to the cryptographic module are listed below, all must be present in order for the module authentication to succeed:

• entbase.jar
• entcapi.jar
• entp5.jar
• entp11.jar
• entp12.jar
• entroaming.jar

Or:

• enttoolkit.jar

For people who wish to use the Toolkit in non-FIPS mode, no additional calls need to be made; by default the Toolkit operates in non-FIPS mode. For people who with to use the Toolkit in FIPS mode, the following call must be made at the start of their program:

SecurityEngine.initialize( true );

Once this call has been made, the Toolkit will operate in compliance with FIPS 140-2 level 1. For more information on FIPS, please refer to NIST

FIPS 140-2:

This class is part of the Toolkit's FIPS 140-2 cryptographic module and contains APIs that are considered part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; refer to the API documentation for further details

Field Summary

Fields

Modifier and Type	Field and Description
static byte[]	EMPTY_BYTE_ARRAY Data returned when in FIPS ERROR state.
static int	ERROR Constant to indicate the ERROR state as required by FIPS 140-2.
static java.lang.String	FIPS_VERSION Contains the version of the FIPS boundary
static int	OPERATIONAL Constant to indicate that the Security Engine is in the non-FIPS operational state.
static int	OPERATIONAL_FIPS Constant to indicate that the Security Engine is in the FIPS operational state whereby FIPS requirements are enforced.
static int	SELF_TESTING Constant to indicate that the Security Engine is in the SELF_TESTING state.

Constructor Summary

Constructors

Constructor and Description
SecurityEngine()

Method Summary

Modifier and Type	Method and Description
static void	assertCryptoOperationsAllowed() Checks if the Toolkit is allowed to perform cryptographic operations; if not, a SecurityException is thrown indicating this.
static void	doSelfTests() Authenticates the cryptographic module and runs all algorithm self-tests on the cryptographic module.
static int	getState() Return the state of the FIPS Security Engine.
static void	initialize(boolean fipsMode) Initializes the Toolkit in FIPS or non-FIPS mode.
static boolean	isCryptoOperationsAllowed() Returns true if the Toolkit is allowed to perform cryptographic operations; otherwise false is returned.
static boolean	isInFIPSMode() Returns true if the Security Engine is in FIPS mode; otherwise false is returned.
static void	setErrorState(java.lang.String errorMessage) Forces the FIPS Security Engine into the FIPS ERROR state.

Methods inherited from class java.lang.Object

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

Field Detail

OPERATIONAL

public static final int OPERATIONAL

Constant to indicate that the Security Engine is in the non-FIPS operational state. All operations are allowed and FIPS requirements are not enforced. By default, the SecurityEngine starts in this state. It may be transitioned to from either the ERROR state or the FIPS_OPERATIONAL state by initializing in non-FIPS mode.

See Also:

Constant Field Values

SELF_TESTING

public static final int SELF_TESTING

Constant to indicate that the Security Engine is in the SELF_TESTING state. While in this state the FIPS algorithm self-tests are performed. It is a temporary state that may be transitioned to from either the ERROR state or OPERATIONAL state by initializing in FIPS mode.

See Also:

Constant Field Values

OPERATIONAL_FIPS

public static final int OPERATIONAL_FIPS

Constant to indicate that the Security Engine is in the FIPS operational state whereby FIPS requirements are enforced. It is transitioned to following successful completion of cryptographic module authentication and algorithm self-tests from the SELF_TESTING state.

See Also:

Constant Field Values

ERROR

public static final int ERROR

Constant to indicate the ERROR state as required by FIPS 140-2. When in this state, the cryptographic module will not perform any cryptographic operations and no data will be output across the data output interface. This state is transitioned into when cryptographic module authentication fails, any of the power-up known-answer tests fail, or any of the conditional test fail. When in this state, it may only transitioned out of by re-initializing.

See Also:

Constant Field Values

EMPTY_BYTE_ARRAY

public static final byte[] EMPTY_BYTE_ARRAY

Data returned when in FIPS ERROR state.

FIPS_VERSION

public static final java.lang.String FIPS_VERSION

Contains the version of the FIPS boundary

Since:

8.1

See Also:

Constant Field Values

Constructor Detail

SecurityEngine

public SecurityEngine()

Method Detail

initialize

public static void initialize(boolean fipsMode)
                       throws java.lang.SecurityException

Initializes the Toolkit in FIPS or non-FIPS mode.

To initialize in non-FIPS mode, call this function with fipsMode set to false. When calling this function with fipsMode set to true, it will attempt to initialize in FIPS mode. If the initialization was unsuccessful, the FIPS ERROR state results.

Note

Once initialized in FIPS mode, the Toolkit cannot be re-initialized to non-FIPS mode.

FIPS 140-2:

FIPS Service: Module Initialization

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

fipsMode - [FIPS 140-2 control input] true for initializing in FIPS mode; false otherwise

Throws:

java.lang.SecurityException - [FIPS 140-2 status output] thrown if FIPS power up self-tests fail

doSelfTests

public static void doSelfTests()
                        throws java.lang.SecurityException

Authenticates the cryptographic module and runs all algorithm self-tests on the cryptographic module.

If the tests are all successful, a state transition to OPERATIONAL_FIPS occurs; if the tests fail, a state transition to ERROR occurs.

FIPS 140-2:

FIPS Service: Perform Self-Tests

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

Throws:

java.lang.SecurityException - [FIPS 140-2 status output] thrown if any of the self-tests fail

getState

public static int getState()

Return the state of the FIPS Security Engine. The following states can be returned:

• OPERATIONAL
• SELF_TESTING
• OPERATIONAL_FIPS
• ERROR

FIPS 140-2:

FIPS Service: Show Status

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions, return value)

Returns:

[FIPS 140-2 status output] the state of the FIPS Security Engine

setErrorState

public static void setErrorState(java.lang.String errorMessage)

Forces the FIPS Security Engine into the FIPS ERROR state.

Users should never call this function as it will restrict cryptographic functionality. Its purpose is to allow power-up test failure and conditional test failure to result in the FIPS ERROR state.

FIPS 140-2:

FIPS Service: Show Status

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call, parameters)
• status output interface (exceptions)

Parameters:

errorMessage - [FIPS 140-2 control input] message indicating why the FIPS Security Engine is being put in the FIPS ERROR state

Throws:

java.lang.SecurityException - [FIPS 140-2 status output] always thrown; contains the provided error message

isInFIPSMode

public static boolean isInFIPSMode()

Returns true if the Security Engine is in FIPS mode; otherwise false is returned.

When in FIPS mode, the FIPS Security Engine enforces FIPS requirements.

FIPS 140-2:

FIPS Service: Show Status

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions, return value)

Returns:

[FIPS 140-2 status output] true if the Security Engine is in FIPS mode; false otherwise

isCryptoOperationsAllowed

public static boolean isCryptoOperationsAllowed()

Returns true if the Toolkit is allowed to perform cryptographic operations; otherwise false is returned.

Cryptographic operation are not permitted when in the FIPS ERROR state.

FIPS 140-2:

FIPS Service: Show Status

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions, return value)

Returns:

[FIPS 140-2 status output] true if the Toolkit is allowed to perform cryptographic operations; false otherwise

assertCryptoOperationsAllowed

public static void assertCryptoOperationsAllowed()
                                          throws Fips140ErrorStateException

Checks if the Toolkit is allowed to perform cryptographic operations; if not, a SecurityException is thrown indicating this.

Cryptographic operations are not permitted when in the FIPS ERROR state.

FIPS 140-2:

FIPS Service: Show Status

This API is part of the logical interface to the Toolkit's FIPS 140-2 cryptographic module; use of this API causes the caller to assume the FIPS 140-2 crypto officer role and accesses the following FIPS 140-2 logical interfaces:

• control input interface (API call)
• status output interface (exceptions)

Throws:

Fips140ErrorStateException - [FIPS 140-2 status output] thrown if the Toolkit is not allowed to perform cryptographic operations