com.rsa.jsafe.crypto
Class CryptoJ

java.lang.Object
  com.rsa.jsafe.crypto.CryptoJ

public final class CryptoJ

extends Object

This is the Crypto-J "master class." It keeps the version number and enables FIPS-related self-testing on a FIPS-validated version of the toolkit.

CryptoJ has methods to allow the user run the FIPS-required power-up self-tests on demand and get their status, methods to set and query the user role, and methods to get and set the library to fips or non-fips mode. These methods are not available on a non-fips library.

The FIPS version of CryptoJ executes power-up self-tests automatically upon startup and conditional tests at runtime. Upon startup failure, the toolkit enters a FAILED state preventing further operation.

See Overview of Crypto-J for background and reference material on using and understanding Crypto-J.

Copyright © RSA Security Inc., 1997-2005. All rights reserved.

Field Summary
static String	CRYPTO_J_VERSION The current version of Crypto-J.
static int	CRYPTO_OFFICER_ROLE Denotes the Crypto Officer role.
static int	FAILED Indicates that the toolkit failed verification; a powerup or a conditional self test has failed.
static int	FIPS_MODE Indicates that the tookit is running in FIPS mode.
static int	FIPS_TESTING_MODE Indicates that the toolkit is running in FIPS testing mode.
static int	NON_FIPS_MODE Indicates that the toolkit is running in non-FIPS mode.
static int	NOT_INITIALIZED Indicates that the tookit has not been verified
static int	OPERATIONAL Indicates that the toolkit passed verification.
static byte[]	savedQBytes saved Q bytes for testing a fips 186 random and acts as a flag
static byte[]	savedXKEYBytes saved XKEY bytes for testing a fips 186 random and acts as a flag
static int	UNDER_SELF_TEST Indicates that the toolkit is under self test
static int	USER_ROLE Denotes the normal user role.

 

Method Summary
static void	checkIntegrity() This method is called by the checkIntegrity() methods in JSAFE_Obect, JSAFE_Obfuscator and JSAFE_SecureRandom.
static void	disableLibrary(JsafeJCE provider) Disables the library.
static void	fips186RandomClearQ(SecureRandom random) Resets the prime Q to its default value.
static void	fips186RandomClearXKEY(SecureRandom random) Clears the the interal state of the random.
static void	fips186RandomSetQ(SecureRandom random, byte[] qBytes) Sets the prime Q to the given value.
static void	fips186RandomSetXKEY(SecureRandom random, byte[] XKEYBytes) Sets the internal seed of the random to the given value.
static CryptoJ	getInstance() A factory method that gets a CryptoJ instance.
static int	getMode() Returns the mode, either FIPS or NON-FIPS.
static int	getRole() Returns the user role.
static SecureRandom	getSeeder() Returns the global seed generator.
static int	getState() Queries the toolkit execution state on a FIPS-validated library.
static byte[][]	getX931TestResult() Extracts the results of the last run of the X931 RSA Key Generation Test.
static boolean	isFIPS140Compliant() Indicates whether this toolkit is FIPS 140-2 compliant.
static void	main(String[] args) This main method prints the version number on a non-FIPS toolkit and runs any or all of the known answer tests used in power-up self-testing on a FIPS-validated library.
static void	powerUpSelfTest() Performs the required power up tests once.
static boolean	runSelfTests() Runs the FIPS 140-2 required power-up self-tests on demand.
static boolean	selfTestPassed() Retrieves the results of last execution of the power-up self-tests.
static void	setMode(int newMode) Sets the FIPS mode to newMode.
static void	setRole(int newRole) Sets the user mode to newRole.
static void	setX931TestResult(byte[][] result) Saves the results of the last KeyGenRSA test.

 

Methods inherited from class java.lang.Object

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

 

Field Detail

CRYPTO_J_VERSION

public static final String CRYPTO_J_VERSION

The current version of Crypto-J.

See Also:

Constant Field Values

NOT_INITIALIZED

public static final int NOT_INITIALIZED

Indicates that the tookit has not been verified

See Also:

Constant Field Values

UNDER_SELF_TEST

public static final int UNDER_SELF_TEST

Indicates that the toolkit is under self test

See Also:

Constant Field Values

OPERATIONAL

public static final int OPERATIONAL

Indicates that the toolkit passed verification.

See Also:

Constant Field Values

FAILED

public static final int FAILED

Indicates that the toolkit failed verification; a powerup or a conditional self test has failed.

See Also:

Constant Field Values

FIPS_MODE

public static final int FIPS_MODE

Indicates that the tookit is running in FIPS mode.

See Also:

Constant Field Values

NON_FIPS_MODE

public static final int NON_FIPS_MODE

Indicates that the toolkit is running in non-FIPS mode.

See Also:

Constant Field Values

FIPS_TESTING_MODE

public static final int FIPS_TESTING_MODE

Indicates that the toolkit is running in FIPS testing mode.

See Also:

Constant Field Values

CRYPTO_OFFICER_ROLE

public static final int CRYPTO_OFFICER_ROLE

Denotes the Crypto Officer role.

See Also:

Constant Field Values

USER_ROLE

public static final int USER_ROLE

Denotes the normal user role.

See Also:

Constant Field Values

savedQBytes

public static byte[] savedQBytes

saved Q bytes for testing a fips 186 random and acts as a flag

savedXKEYBytes

public static byte[] savedXKEYBytes

saved XKEY bytes for testing a fips 186 random and acts as a flag

getInstance

public static CryptoJ getInstance()

A factory method that gets a CryptoJ instance.

getSeeder

public static SecureRandom getSeeder()

Returns the global seed generator.

This method is a convenience for users that may need to rely on autoseeding. It allows access to the library's shared seed generation object. Crypto-J keeps a globaly shared SecureRandom of the default provider from which it extracts seed bytes in order to seed other random number generators. These bytes are computed using the seed generation algorithm that this class of the default provider uses to seed itself. The caller may add entropy to this object or trigger autoseeding at a time convenient to the application.

Returns:

the Crypto-J global seed generator

isFIPS140Compliant

public static final boolean isFIPS140Compliant()

Indicates whether this toolkit is FIPS 140-2 compliant. If it is compliant, then methods to query and set the FIPS mode, the user role, and run the power-up tests are available; otherwise, these methods are not available.

There is no enforcement of algorithm selection on FIPS_MODE, the caller is resposible for choosing the proper algorithms.

Returns:

true if this is a FIPS 140-2 compliant library; otherwise, false.

See Also:

getState(), getMode(), setMode(int), getRole(), setRole(int), selfTestPassed(), runSelfTests()

getState

public static int getState()

Queries the toolkit execution state on a FIPS-validated library.

Returns:

The execution state, NOT_INITIALIZED, UNDER_SELF_TEST, OPERATIONAL, or FAILED.

See Also:

isFIPS140Compliant()

getMode

public static int getMode()

Returns the mode, either FIPS or NON-FIPS. The FIPS mode is meaningful only in a FIPS-validated library.

Returns:

The mode: FIPS_MODE or NON_FIPS_MODE.

See Also:

isFIPS140Compliant(), setMode(int)

setMode

public static void setMode(int newMode)
                    throws com.rsa.jsafe.crypto.JSAFE_InvalidUseException

Sets the FIPS mode to newMode. The paramater newMode must be one of FIPS_MODE or NON_FIPS_MODE and the library must be a FIPS-validated library. There is no enforcement of algorithm selection on FIPS_MODE, the caller is resposible for choosing the proper algorithms.

Parameters:

newMode - The desired mode, FIPS_MODE or NON_FIPS_MODE

Throws:

JSAFE_InvalidUseException - If newMode is not an allowed value or the library is not a FIPS-compliant library.

See Also:

isFIPS140Compliant(), getMode()

getRole

public static int getRole()

Returns the user role. The user role is meaninful only on a FIPS-validated library.

Returns:

The user role, USER_ROLE or CRYPTO_OFFICER_ROLE.

See Also:

isFIPS140Compliant(), setRole(int)

setRole

public static void setRole(int newRole)
                    throws com.rsa.jsafe.crypto.JSAFE_InvalidUseException

Sets the user mode to newRole. For use with a FIPS-validated library.

Parameters:

newRole - The desired role, USER_ROLE or CRYPTO_OFFICER_ROLE.

Throws:

JSAFE_InvalidUseException - If newRode is not an allowed value or the library is not a FIPS-validated library.

See Also:

isFIPS140Compliant(), getRole()

disableLibrary

public static void disableLibrary(JsafeJCE provider)

Disables the library. This is used by JsafeJCE provider when its self integrity check fails.

Parameters:

provider - the instance of the JsafeJCE provider

powerUpSelfTest

public static void powerUpSelfTest()

Performs the required power up tests once. Calls a self integrity check and runs the power-up self tests. This method is called at class load time from static code blocks.

powerUpSelfTest differs from runSelfTests, which it calls self-autheticantion and throws a SecurityException if any test fails.

This method is invoked from static code blocks in the JSAFE_Object, JSAFE_SecureRandom, and JSAFE_Obfuscator classes to ensure that it will be called authomatically. All public Cryptographic Transformation classes extend one of these three classes so the Java Runtime will execute the static code blocks at load time thus ensuring that the powerup test get executed automatically.

selfTestPassed

public static boolean selfTestPassed()

Retrieves the results of last execution of the power-up self-tests. This method should be called on a FIPS-validated library only.

Returns:

true if all the self-tests passed; otherwise, false.

See Also:

isFIPS140Compliant()

runSelfTests

public static boolean runSelfTests()
                            throws com.rsa.jsafe.crypto.JSAFE_InvalidUseException

Runs the FIPS 140-2 required power-up self-tests on demand. For use by the Crypto Officer with a FIPS-validated library.

These tests consist of the algorithm known answer tests plus pairwise consistency checks on DSA and RSA key pair generation.

Returns:

true if all the self-tests passed; otherwise, false.

Throws:

com.rsa.jsafe.crypto.JSAFE_InvalidUseException

See Also:

isFIPS140Compliant(), selfTestPassed()

checkIntegrity

public static final void checkIntegrity()

This method is called by the checkIntegrity() methods in JSAFE_Obect, JSAFE_Obfuscator and JSAFE_SecureRandom. What is checks for is that the toolkit is still operational and has not become disabled by failing any self test, power up or conditional.

fips186RandomClearQ

public static void fips186RandomClearQ(SecureRandom random)

Resets the prime Q to its default value.

This method is for use in CRYPTO_OFFICER_ROLE when running the FIPS RNG validation suite.

Parameters:

random - a FIPS 186 random to test

fips186RandomSetQ

public static void fips186RandomSetQ(SecureRandom random,
                                     byte[] qBytes)

Sets the prime Q to the given value.

This method is for use in CRYPTO_OFFICER_ROLE when running the FIPS RNG validation suite.

Parameters:

random - a FIPS 186 random to test

qBytes - the value for Q

fips186RandomClearXKEY

public static void fips186RandomClearXKEY(SecureRandom random)

Clears the the interal state of the random.

This method is for use in the CRYPTO_OFFICER_ROLE when running the FIPS RNG validation suite.

Parameters:

random - a FIPS 186 random to test

fips186RandomSetXKEY

public static void fips186RandomSetXKEY(SecureRandom random,
                                        byte[] XKEYBytes)

Sets the internal seed of the random to the given value.

This method is for use in CRYPTO_OFFICER_ROLE when running the FIPS RNG validation suite. Neither the JCE nor the JSAFE API provide a method to set the internal seed of the random. This method allows a NIST RNG validation test to set the initial test of the random in a uniform fashion across the JSAFE and JCE API.

Parameters:

random - a FIPS 186 random to test

XKEYBytes - array containing the XKEY bytes to save.

setX931TestResult

public static void setX931TestResult(byte[][] result)

Saves the results of the last KeyGenRSA test. The JCE API does not provide a way for testing and retrieving results so we save them here.

Parameters:

result - the KeyGenRSA test results to save

getX931TestResult

public static byte[][] getX931TestResult()

Extracts the results of the last run of the X931 RSA Key Generation Test. The JCE API does not provide a way for testing and retrieving results so we save them here at generateKeyPair time and allow the tester to get them later.

Returns:

results of the last KeyGenRSA test

main

public static void main(String[] args)

This main method prints the version number on a non-FIPS toolkit and runs any or all of the known answer tests used in power-up self-testing on a FIPS-validated library.