Table Of Contents

• Overview
• How to Build OpenJCEPlus and Java Native Interface Library
• Test Execution
  • Run All Tests
  • Run Single Test
• OpenJCEPlus and OpenJCEPlusFIPS Provider SDK Installation
• Features and Algorithms
• Contributions

Overview

This project contains source code associated with the OpenJCEPlus and OpenJCEPlusFIPS cryptographic providers that can be used within a Java SDK. At this time, this project intends to only issue source code releases which will not include any binary distribution format. These cryptographic providers contain capabilities to support JCE cryptographic operations using the Open Crypto Kit cryptographic library.

IMPORTANT NOTE: Although this project uses the term "FIPS" in different code paths and naming conventions the code and binary files derived from this code CANNOT be considered FIPS compliant. Achieving certified FIPS cryptography requires the underlying library binary to be FIPS certified for specific platforms and architectures. Any cryptographic libraries developed must adhere to rigorous FIPS standards and should not be assumed to be available in any environment. All environments and binaries must undergo the FIPS certification process with NIST to ensure compliance.

This github branch can only be used with the latest generally available version of Java.

Build Status:

How to Build OpenJCEPlus and Java Native Interface Library

OpenJCEPlus and OpenJCEPlusFIPS providers are currently supported on the following architectures and operating system combinations as reported by mvn --version in the values OS name and arch:

OS name	arch
linux	amd64
linux	s390x
linux	ppc64le
Windows Server 2022	amd64
AIX	ppc64
Mac OS X*	aarch64*
Mac OS X*	amd64*

• Mac OS X currently is only able to compile and run tests using the OpenJCEPlus provider, not OpenJCEPlusFIPS. The provider OpenJCEPlusFIPS will not load.

Follow these steps to build the OpenJCEPlus and OpenJCEPlusFIPS providers along with a dependent Java Native Interface library. Keep in mind that $PROJECT_HOME can represent any directory on your system and will be referred to as such in the subsequent instructions. Also keep in mind that the value $JAVA_VERSION below must match the same version of the branch of OpenJCEPlus being built. For example if building the java21 branch the $JAVA_VERSION must match the Java 21 SDK version such as 21.0.2+13.

1. Create an OCK directory, for example:

   mkdir $PROJECT_HOME/OCK

2. Follow instructions available in the project OpenCryptographyKitC to build both the SDK tar file and the binary distribution tar file. You can also refer to this projects github-actions.yml file for details on how this project incorporates and builds the OpenCryptographyKitC project for testing purposes.

3. Extract the Java gskit SDK tar and gskit tar file into the directory previously created:

   cd $PROJECT_HOME/OCK
   tar xvf jgsk_crypto_8_9_3_0_sdk.tar
   tar xvf jgsk_crypto_8_9_3_0.tar

4. Copy the OCK library referred to as ICC to the correct location:

   Based on the platform, the library file (i.e., $LIBJGSKIT_LIBRARY) is named differently. The values are as follows:

   • AIX/Linux: libjgsk8iccs_64.so
   • Mac OS X: libjgsk8iccs.dylib
   • Windows: jgsk8iccs_64.dll

   Create the lib64 directory and copy the $LIBJGSKIT_LIBRARY library to that location:

   mkdir $PROJECT_HOME/OCK/jgsk_sdk/lib64
   cp $PROJECT_HOME/OCK/$LIBJGSKIT_LIBRARY $PROJECT_HOME/OCK/jgsk_sdk/lib64

   On AIX also copy the library to the jgsk_sdk directory in addition to the lib64 directory above.

   cp $PROJECT_HOME/OCK/$LIBJGSKIT_LIBRARY $PROJECT_HOME/OCK/jgsk_sdk

5. Install Maven and place the command in your PATH. These instructions are OS dependant. It is recommended to make use of version 3.9.2, although other versions of Maven are known to work. You can test your installation by issuing mvn --version. For example:

   $ mvn --version
   Apache Maven 3.9.2 (c9616018c7a021c1c39be70fb2843d6f5f9b8a1c)
   Maven home: /tools/apache-maven-3.9.2
   Java version: $JAVA_VERSION, vendor: IBM Corporation, runtime: /opt/ibm/sdks/jdk-$JAVA_VERSION
   Default locale: en_US, platform encoding: ISO8859-1
   OS name: "aix", version: "7.2", arch: "ppc64", family: "unix"

6. Clone the OpenJCEPlus repository.

7. Change directory to the root directory where the pom.xml file exists.

   cd OpenJCEPlus

8. Set your JAVA_HOME environment variable. This will be the SDK used to compile the project. You must set your JAVA_HOME value to the latest generally available version of Java when using code located in the main branch.

   export JAVA_HOME="/opt/ibm/sdks/jdk-$JAVA_VERSION"

9. Set the location of the variable GSKIT_SDK to the directory extracted in the above steps.

   export GSKIT_HOME="$PROJECT_HOME/OCK/jgsk_sdk"

10. (Only for Windows) Some additional environment variables need to be set in Windows. There are certain header files and libraries that are required to build the OpenJCEPlus and OpenJCEPlusFIPS providers in a Windows environment and those files are found in the exported directories. It is assumed that you are running through a CYGWIN prompt.

    export PATH=/cygdrive/c/Program\ Files\ \(x86\)/Windows\ Kits/10/bin/10.0.19041.0/x64/:/cygdrive/c/Program\ Files/Microsoft\ Visual\ Studio/2022/Professional/VC/Tools/MSVC/14.31.31103/bin/Hostx64/x64/:$PATH
    
    export INCLUDE="C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/um/;C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/shared/;C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.31.31103/include/;C:/Program Files (x86)/Windows Kits/10/include/10.0.19041.0/ucrt/"
    
    export LIB="C:/Program Files/Microsoft Visual Studio/2022/Professional/VC/Tools/MSVC/14.31.31103/lib/x64;C:/Program Files (x86)/Windows Kits/10/lib/10.0.19041.0/ucrt/x64;C:/Program Files (x86)/Windows Kits/10/lib/10.0.19041.0/um/x64"

    NOTE 1: You need to have installed Microsoft Visual Studio and CYGWIN on your machine.

    NOTE 2: You might have to adapt the exported environment variables, if the installation directory of Visual Studio is different on your machine, or the versions you have available for Windows Kits and Visual Studio are diffent (e.g., the Windows Kits version in the variables above is 10.0.19041.0, but it might be different on your machine).

11. Compile the OpenJCEPlus and OpenJCEPlusFIPS providers along with the Java Native Interface library. This command intentionally skips test execution. See instructions below for running tests.

    mvn '-Dock.library.path=$PROJECT_HOME/OCK/' install -DskipTests

    On Mac:

    mvn '-Dock.library.path=$PROJECT_HOME/OCK/jgsk_crypto' install -DskipTests

Test Execution

Tests are available within the OpenJCEPlus repository. These Junit tests can be run in various ways including running individual tests or the entire test suite.

Run all tests

On AIX:

• You must set an additional setting for the LIBPATH environment variable:

 export LIBPATH="$PROJECT_HOME/OCK/:$PROJECT_HOME/OCK/jgsk_sdk"

• If you are using a JDK that bundles OpenJCEPlus, like Semeru, and you want to make sure that you use an OCK library different than the one bundled with the JDK, you need to delete the bundled one. More specifically you need to run:

 rm $JAVA_INSTALL_DIRECTORY/jdk-$JAVA_VERSION/lib/libjgsk8iccs_64.so
 rm -rf $JAVA_INSTALL_DIRECTORY/jdk-$JAVA_VERSION/lib/C
 rm -rf $JAVA_INSTALL_DIRECTORY/jdk-$JAVA_VERSION/lib/N

On all platforms set the following environment variables and execute all the tests using mvn. You must set your JAVA_HOME value to the latest generally available version of Java when using code located in the main branch.

export JAVA_HOME="$JAVA_INSTALL_DIRECTORY/jdk-$JAVA_VERSION"
export GSKIT_HOME="$PROJECT_HOME/OCK/jgsk_sdk"
mvn '-Dock.library.path=$PROJECT_HOME/OCK/' test

NOTE: When using a JDK that doesn't have OpenJCEPlus bundled with it, you might notice a few warnings like WARNING: Unknown module: openjceplus specified to --add-exports. There is no need to worry as they do not affect execution of tests or the build itself.

Run single test

On AIX you must set an additional setting for the LIBPATH environment variable:

export LIBPATH="$PROJECT_HOME/OCK/:$PROJECT_HOME/OCK/jgsk_sdk"

On all platforms change to the OpenJCEPlus directory and set the following environment variables and execute a specific test name using mvn. You must set your JAVA_HOME value to the latest generally available version of Java when using code located in the main branch.

cd OpenJCEPlus
export JAVA_HOME="$JAVA_INSTALL_DIRECTORY/jdk-$JAVA_VERSION"
export GSKIT_HOME="$PROJECT_HOME/OCK/jgsk_sdk"
mvn '-Dock.library.path=$PROJECT_HOME/OCK/' test -Dtest=TestClassname

OpenJCEPlus and OpenJCEPlusFIPS Provider SDK Installation

1. Modify your java.security file located in the $JAVA_HOME/conf/security directory by adding one of the following providers. The value XX below represents your desired preference order.

   security.provider.XX=com.ibm.crypto.plus.provider.OpenJCEPlusFIPS
   security.provider.XX=com.ibm.crypto.plus.provider.OpenJCEPlus

2. Execute your application specifying the openjceplus.jar, the location of the OCK library, and the location of the jgskit library as follows.

   -Xbootclasspath/a:$ANYDIRECTORY/openjceplus.jar

   '-Dock.library.path=$PROJECT_HOME/OCK/'

   -Djgskit.library.path=$ANYDIRECTORY

Features And Algorithms

The following algorithms are registered by the OpenJCEPlus and OpenJCEPlusFIPS providers.

Algorithm Type	Algorithm Name	OpenJCEPlusFIPS	OpenJCEPlus
AlgorithmParameterGenerator	CCM	X	X
AlgorithmParameterGenerator	DSA		X
AlgorithmParameterGenerator	DiffieHellman	X	X
AlgorithmParameterGenerator	EC	X	X
AlgorithmParameterGenerator	GCM	X	X
AlgorithmParameters	AES	X	X
AlgorithmParameters	CCM	X	X
AlgorithmParameters	ChaCha20-Poly1305		X
AlgorithmParameters	DESede		X
AlgorithmParameters	DSA	X	X
AlgorithmParameters	DiffieHellman	X	X
AlgorithmParameters	EC	X	X
AlgorithmParameters	GCM	X	X
AlgorithmParameters	OAEP	X	X
AlgorithmParameters	RSAPSS	X	X
Cipher	AES	X	X
Cipher	AES/CCM/NoPadding	X	X
Cipher	AES/GCM/NoPadding	X	X
Cipher	ChaCha20		X
Cipher	ChaCha20-Poly1305		X
Cipher	DESede		X
Cipher	RSA	X	X
KeyAgreement	DiffieHellman	X	X
KeyAgreement	ECDH	X	X
KeyAgreement	X25519		X
KeyAgreement	X448		X
KeyAgreement	XDH		X
KeyFactory	DSA	X	X
KeyFactory	DiffieHellman	X	X
KeyFactory	EC	X	X
KeyFactory	Ed25519		X
KeyFactory	Ed448		X
KeyFactory	EdDSA		X
KeyFactory	RSA	X	X
KeyFactory	RSAPSS	X	X
KeyFactory	X25519		X
KeyFactory	X448		X
KeyFactory	XDH		X
KeyGenerator	AES	X	X
KeyGenerator	ChaCha20		X
KeyGenerator	DESede		X
KeyGenerator	HmacMD5		X
KeyGenerator	HmacSHA1		X
KeyGenerator	HmacSHA224	X	X
KeyGenerator	HmacSHA256	X	X
KeyGenerator	HmacSHA3-224	X	X
KeyGenerator	HmacSHA3-256	X	X
KeyGenerator	HmacSHA3-384	X	X
KeyGenerator	HmacSHA3-512	X	X
KeyGenerator	HmacSHA384	X	X
KeyGenerator	HmacSHA512	X	X
KeyGenerator	SunTls12KeyMaterial	X	X
KeyGenerator	SunTls12MasterSecret	X	X
KeyGenerator	SunTls12Prf	X	X
KeyGenerator	SunTls12RsaPremasterSecret	X	X
KeyGenerator	SunTlsKeyMaterial	X	X
KeyGenerator	SunTlsMasterSecret	X	X
KeyGenerator	SunTlsPrf	X	X
KeyGenerator	SunTlsRsaPremasterSecret	X	X
KeyGenerator	kda-hkdf-with-sha1		X
KeyGenerator	kda-hkdf-with-sha224	X	X
KeyGenerator	kda-hkdf-with-sha256	X	X
KeyGenerator	kda-hkdf-with-sha384	X	X
KeyGenerator	kda-hkdf-with-sha512	X	X
KeyPairGenerator	DSA		X
KeyPairGenerator	DiffieHellman	X	X
KeyPairGenerator	EC	X	X
KeyPairGenerator	Ed25519		X
KeyPairGenerator	Ed448		X
KeyPairGenerator	EdDSA		X
KeyPairGenerator	RSA	X	X
KeyPairGenerator	RSAPSS	X	X
KeyPairGenerator	X25519		X
KeyPairGenerator	X448		X
KeyPairGenerator	XDH		X
Mac	HmacMD5		X
Mac	HmacSHA1		X
Mac	HmacSHA224	X	X
Mac	HmacSHA256	X	X
Mac	HmacSHA3-224	X	X
Mac	HmacSHA3-256	X	X
Mac	HmacSHA3-384	X	X
Mac	HmacSHA3-512	X	X
Mac	HmacSHA384	X	X
Mac	HmacSHA512	X	X
MessageDigest	MD5	X	X
MessageDigest	SHA-1	X	X
MessageDigest	SHA-224	X	X
MessageDigest	SHA-256	X	X
MessageDigest	SHA-384	X	X
MessageDigest	SHA-512	X	X
MessageDigest	SHA-512/224	X	X
MessageDigest	SHA-512/256	X	X
MessageDigest	SHA3-224	X	X
MessageDigest	SHA3-256	X	X
MessageDigest	SHA3-384	X	X
MessageDigest	SHA3-512	X	X
SecretKeyFactory	AES	X	X
SecretKeyFactory	ChaCha20		X
SecretKeyFactory	DESede		X
SecureRandom	SHA256DRBG	X	X
SecureRandom	SHA512DRBG	X	X
Signature	Ed25519		X
Signature	Ed448		X
Signature	EdDSA	X	X
Signature	NONEwithDSA	X	X
Signature	NONEwithECDSA	X	X
Signature	NONEwithRSA	X	X
Signature	RSAPSS	X	X
Signature	RSAforSSL	X	X
Signature	SHA1withDSA		X
Signature	SHA1withECDSA		X
Signature	SHA1withRSA	X	X
Signature	SHA224withDSA	X	X
Signature	SHA224withECDSA	X	X
Signature	SHA224withRSA	X	X
Signature	SHA256withDSA	X	X
Signature	SHA256withECDSA	X	X
Signature	SHA256withRSA	X	X
Signature	SHA3-224withDSA		X
Signature	SHA3-224withECDSA		X
Signature	SHA3-224withRSA		X
Signature	SHA3-256withDSA		X
Signature	SHA3-256withECDSA		X
Signature	SHA3-256withRSA		X
Signature	SHA3-384withDSA		X
Signature	SHA3-384withECDSA		X
Signature	SHA3-384withRSA		X
Signature	SHA3-512withDSA		X
Signature	SHA3-512withECDSA		X
Signature	SHA3-512withRSA		X
Signature	SHA384withECDSA	X	X
Signature	SHA384withRSA	X	X
Signature	SHA512withECDSA	X	X
Signature	SHA512withRSA	X	X

Contributions

The following contribution guidelines should be followed:

1. Code should be styled according to the included style.xml eclipse rules.

2. A pull request should be sent for review only after the github action associated with this repository is automatically executed when a pull request is created.

3. AI generated code is NOT allowed in the main line cryptographic code (i.e. All code in OpenJCEPlus/src/main directory). However, it maybe used for test code. If GenAI code is used it must be tagged. The begin tag needs to indicate the GenAI tool used to create the code.

   Here are more guidelines:

   • All code that incorporates any output from GenAI tool must be tagged regardless of whether the tag automatically appears in the output or you are manually re-typing GenAI output

   • This applies to all GenAI outputs regardless of the use case.

   • You MUST validate that the use of the GenAI tool does not produce protected code (i.e. code that is copyrighted or licensed outside of our project's current licenses).

   An example of a tagging would be:

    /* Start code generated by <GenAI tool> */

 

    /* End code  generated by <GenAI tool> */