FIPS 140-3 cryptography in IBM Semeru Runtimes

The FIPS 140-2 cryptographic security standard from the US government is now superseded by a later version, FIPS 140-3. The existing Semeru FIPS 140-2 support is currently unchanged, but will be deprecated in future. The documentation for the 140-2 solution is available here FIPS certified cryptography in IBM Semeru Runtimes. 

The FIPS 140-3 cryptographic module within the Semeru SDK has been approved by NIST in August 2024 and is fully supported for production use. Refer to section FIPS Certification for further information including a link to the NIST certification documentation.

Note: Information in this guide does not apply for the IBM Semeru Runtime Certified Edition for z/OS. For more information about the certified edition, see IBM Semeru Runtime Certified Edition for z/OS documentation.

The FIPS 140-3 functionality described in this document is based on code contained in two open-source projects.

1. The OpenJCEPlusFIPS provider located at OpenJCEPlus.

2. The Open Cryptography Kit for C located at OpenCryptographyKitC.

FIPS certification

Semeru runtimes contain a FIPS 140-3 certified cryptographic library that has been certified by NIST. The NIST certification associated with the FIPS 140-3 module can be viewed at https://csrc.nist.gov/projects/cryptographic-module-validation-program/certificate/4755

An updated version of the IBM Crypto for C module has been released as an open-source project called Open Cryptography Kit for C located at OpenCryptographyKitC. The Open Cryptography Kit for C code base has been validated by NIST and certification has been issued confirming that it meets the FIPS 140-3 standard. The FIPS 140-3 standard is stricter than FIPS 140-2, so you might need to change your applications and or configurations to migrate and make use of FIPS 140-3. 

Operational environments

Production ready FIPS 140-3 code is available in Semeru runtime versions 11.0.24, 17.0.12, and Java 21.0.4 or higher. To enable FIPS 140-3, see section Enabling FIPS 140-3.

In Semeru runtime versions 11.0.23, 17.0.10.0, and Java 21.0.3.0 FIPS 140-3 was available as a technical preview functionality only.

The following system architectures are currently supported:

• AIX on 64-bit IBM POWER hardware
• Linux on x86-64 hardware
• Linux (Little Endian) on 64-bit IBM POWER hardware
• Windows on x86-64 hardware

Note: The FIPS 140-3 security policy does not permit the use of the OpenJCEPlusFIPS provider on 32-bit operating systems.

FIPS 140-2 statement of direction and future deprecation

The FIPS 140-2 solution, which makes use of the NSS library, will be deprecated in the future in favor of the FIPS 140-3 production ready solution described in this document. The FIPS 140-3 cryptographic modules are approved for production use, and a certificate has been issued by NIST. In a future release the -Dsemeru.fips Java property will default to use FIPS 140-3. The exact date of deprecation will be determined at a later time.

Java restricted security mode profiles

A restricted security mode profile represents a collection of properties that configures a Java runtime environment from a security perspective. Two restricted security profiles are included within Semeru to support the OpenJCEPlusFIPS provider and aid users in implementing the FIPS 140-3 standard. The two profiles are referred to as FIPS140-3-Weakly-Enforced and the stricter FIPS140-3 profiles. Details about these profiles are described here.

1. FIPS140-3-Weakly-Enforced restricted security mode profile

This profile is the default profile when using the -Dsemeru.fips=true -Dsemeru.customprofile=OpenJCEPlusFIPS set of Java properties. To explicitly enable the FIPS140-3-Weakly-Enforced profile, use -Dsemeru.fips=true -Dsemeru.customprofile=OpenJCEPlusFIPS.FIPS140-3-Weakly-Enforced. This profile allows for all algorithms within the OpenJCEPlusFIPS provider to be preferred over other cryptographic providers. Certain algorithms included in the OpenJCEPlusFIPS provider may or may not be allowed under the FIPS 140-3 standard according to the FIPS security policy. This profile includes other cryptographic and non-cryptographic algorithms from non-FIPS providers typically used by applications. For example, PKCS12 files are pre-configured.

Note: This profile allows for algorithm use such that a given application deployment may not achieve FIPS compliance.

2. FIPS140-3 restricted security mode profile

Explicitly enable the strict FIPS140-3 profile by using the following Java properties:

-Dsemeru.fips=true -Dsemeru.customprofile=OpenJCEPlusFIPS.FIPS140-3

This profile represents only FIPS 140-3 approved cryptography in the OpenJCEPlusFIPS provider along with other non-cryptographic algorithms that are allowable, or are unrelated, to the FIPS 140-3 standard. Note that numerous algorithms have been removed from the OpenJCEPlusFIPS provider as compared to the FIPS140-3-Weakly-Enforced profile. Refer to the java.security file for additional information on specific algorithms, and the corresponding constraints, that have been used to remove various algorithms for this profile.

Additional providers are removed from this profile to ensure users are given a strict set of algorithms to allow for a given application to achieve FIPS 140-3 compliance.

Creating extensions of profiles

Any profile, existing in the JDK or user-specified, can be further extended in a manner similar to class extensions in Java. All properties of the extended profile are by default inherited, but can be changed, by the extending profile. Users are advised to create their own profiles that represent their FIPS 140-3 specific deployment instead of modifying existing profiles that already exist in the java.security file.

To extend a profile, modify the java.security file. This can be done by directly modifying the java.security file or appending to existing java.security files by using –Djava.security.properties=$filename where $filename is the name of the file that contains your custom profile.

This new profile can then be declared using the following syntax:

RestrictedSecurity.$custom_profile_name.extends = RestrictedSecurity.$profile_to_extend

To create a profile to extend the OpenJCEPlusFIPS.FIPS140-3 profile, create a new profile, in the java.security file or in a separate file.

Example java.security file:

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.desc.name = Custom OpenJCEPlusFIPS Cryptographic Module FIPS 140-3 
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.extends = RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3

This simple new profile example has all the properties of the OpenJCEPlusFIPS.FIPS140-3 profile and overrides only the desc.name property. Further information on the options for updating existing properties are discussed in further sections of this guide.

Any property that is inherited by an extended profile can be overridden. This can be achieved by specifying the property in question under the new extending profile. Building on the previous example profile, you could specify the following:

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.desc.name = Custom OpenJCEPlusFIPS Cryptographic Module FIPS 140-3
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.extends = RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.desc.sunsetDate = 2030-09-21
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.jce.provider.3 = sun.security.rsa.SunRsaSign

This overrides the sunset date of the extended custom profile and changes the third provider to be SunRsaSign instead of SunJSSE, which was the case in the base profile. The same principle is applicable to all properties. 

Certain properties are eligible for appending or deleting elements. There are 2 categories:

1. Providers and their constraints

Constraints can be added or removed from a provider. However, note that the provider affected has to be in the same position that it was in the base profile.

For example:

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.desc.name = Custom OpenJCEPlusFIPS Cryptographic Module FIPS 140-3
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.extends = RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.jce.provider.2 = sun.security.provider.Sun [-{CertificateFactory, X.509, ImplementedIn=Software}]
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.jce.provider.3 = sun.security.ssl.SunJSSE [+{Policy, JavaPolicy, *}]

In this example, a constraint is removed from the SUN provider as indicated by the “-” character and one is added to the SunJSSE provider as indicated by the “+” character. Note that both providers are in the same position as they are in the profile being extended. Trying to append or delete constraints from a provider that is in a different position from the base profile results in an exception if the profile is loaded. Moreover, the constraint to be removed must be present in the base profile. If constraints are not available in the base profile and are being removed as part of an extension profile an exception occurs if the profile is loaded.

2. Properties that indicate lists of elements

Elements can be added or removed from the said list, using "+" or "–" symbol, respectively. Note that only elements that exist in the base profile can be removed. Failure to abide by that will lead to an exception when trying to load the extending profile.

Existing properties that fall under this category are:

1. tls.disabledNamedCurves
2. tls.disabledAlgorithms
3. tls.legacyAlgorithms
4. jce.certpath.disabledAlgorithms
5. jce.legacyAlgorithms

For example:

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.desc.name = Custom OpenJCEPlusFIPS Cryptographic Module FIPS 140-3
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.extends = RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.tls.disabledAlgorithms = - anon
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.tls.disabledNamedCurves = + sect571k1

With this custom extending profile, "anon" is removed from the list of algorithms disabled for TLS, and "sect571k1" is added to the disabled named curves for TLS.

PKCS12 and JKS Example

This is an example profile to support both PKCS12 and JKS keystore formats. Refer section Key and certificate storage for details on using keys and certificates. This example profile uses a variety of extension features to accomplish this. The following profile extends the strict base profile, while allowing for PKCS12 and JKS to be used for keystores. MessageDigest SHA-1 is needed if JKS is used.

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-withPKCS12.desc.name = OpenJCEPlusFIPS Cryptographic Module FIPS 140-3 with PKCS12 Support 
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-withPKCS12.extends = RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3 
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-withPKCS12.jce.provider.2 = sun.security.provider.Sun [+ \
  {KeyStore, JKS, *}, \
  {KeyStore, PKCS12, *}, \
  {MessageDigest, SHA-1, *}] 
RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-withPKCS12.jce.provider.4 = com.sun.crypto.provider.SunJCE [ \
  {AlgorithmParameters, PBES2, *}, \
  {AlgorithmParameters, PBEWithHmacSHA256AndAES_256, *}, \
  {SecretKeyFactory, PBEWithMD5AndDES, *}, \
  {Cipher, PBEWithHmacSHA256AndAES_256, *}, \
  {Mac, HmacPBESHA256, *}]

This profile can then be enabled by setting the following properties:

-Dsemeru.fips=true -Dsemeru.customprofile=OpenJCEPlusFIPS.FIPS140-3-withPKCS12

Profile Hashing

To avoid accidental changes, allow application owners to achieve 140-3 compliance, and encourage the extension of profiles, specific hash values have been added to all base profiles. Create your own profiles for the deployments rather than changing the already existing base profiles. Each base (i.e., not extending another) profile has to be accompanied by a hash value that represents the state of the profile. The value is specified using:

RestrictedSecurity.$profile_name.desc.hash = $hash_algorithm:$hash_value

As previously mentioned, this hash value represents a specific state of the profile, meaning that if profile properties are altered in any way, the value is no longer valid, and an exception is thrown as soon as one tries to load the profile in question.

Note: This feature is mandatory for the FIPS140-3 base profiles included with Semeru. It is not required for profiles extending the base profiles. For FIPS140-2 base profiles, as well as any profile that extends another, a hash value is optional, but providing a false one might still lead to an exception thrown.

Fully Qualified Provider Name requirements

Regardless of the type of a profile, and whether it is a base or extending profile, the fully qualified name of a JCE provider is required to configure and make use of a given provider. In any other case, the loading of the profile will fail with an exception. You can check the existing profiles, or the examples provided previously in this guide for reference. For example, a declaration could be as follows. Note the full class name for the provider.

RestrictedSecurity.OpenJCEPlusFIPS.FIPS140-3-Custom.jce.provider.3 = sun.security.rsa.SunRsaSign

Profile sunset date enforcements

The sunset date represents the date when a profile is expected to no longer be in use. The sunset date can be used to enforce policy lifecycles associated with a given application deployment. This becomes very useful when a profile corresponds to a specific FIPS certification date in which a policy is known to be expiring.

Profiles have the option of specifying a sunset date. It is not mandatory to specify this value. If a value is specified, a check will be performed to verify that the profile has not yet expired or been sunset. One can choose to remove existing sunset dates from the base profile by setting the sunset value to null (empty) in the extension profile.

For more information regarding configuration of profiles, refer the section Enabling FIPS 140-3.

Enabling FIPS 140-3

FIPS 140-3 is disabled by default. 

The default java.security file is designed to incorporate a restricted security mode profile, which becomes active upon using a FIPS configuration. A restricted security profile is designed to aid applications in achieving FIPS compliance, by restricting configurations according to settings within the java.security file, associated with a given FIPS configuration name and version. The java.security file profile will encompass settings similar to other settings in the java.security file, except they will be specific for a given applications compliance configuration. Examples include profiles for FIPS 140-2, FIPS 140-3, or various iterations of the FIPS 140 standards. By default, the OpenJCEPlusFIPS provider will be positioned as the primary/first provider in the list when making use of the FIPS 140-3 profile and will coexist alongside profiles that are used for the current 140-2 configuration that makes use of NSS on RHEL FIPS certified systems. Various restrictions will be defined within the profile, including acceptable key sizes, TLS cipher suites, permissible algorithms, and provider configurations.

When configuring security profiles, you must specify one or both of the following options:

Supported algorithms

See the documentation located in the OpenJCEPlus open-source project for more information regarding algorithms provided. Ensure that you view the appropriate git code branch for the Java release that you are working with.

Known limitations

The known limitations are as follows.

• JSSE is currently restricted to known FIPS algorithms as mentioned in the following FAQ section. Additional work is needed in order to support some situations surrounding compliance with RFC 7919 and the predicted FIPS 140-3 security policy. Supported groups may work incorrectly when using the FFDHE algorithm.
• Semeru JRE builds are known to have a failure due to an incorrect format of the file JAVA_HOME/lib/icc/C/libicclib084.so. The workaround is to copy the same dll from the SDK distribution of Semeru into the JRE.

Frequently asked questions

1. SHA1 is not allowed in FIPS 140-3. Can SHA1 still be used to hash two files to determine whether they are the same?

   Yes. SHA1 is no longer considered secure for cryptographic operations. However, you can still use SHA1 for noncryptographic operations. For example, you can use the SHA1 algorithm (from any non-fips provider) to compare two documents or objects to see whether they are identical (same hashes), but you cannot use it for hashing those documents for digital signature.

2. What do you mean by key exchange, bulk encryption or MAC cipher suites?

   A TLS cipher suite is the set of algorithms that are used to secure network connections. In the TLS 1.2 protocol, the set of algorithms that cipher suites usually contain includes: a key exchange algorithm, a bulk encryption algorithm, and a message authentication code (MAC) algorithm. In the cipher suite TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256, for example, ECDHE_RSA is the key exchange algorithm, AES_128_GCM is the bulk encryption algorithm, and SHA256 is the MAC algorithm to be used. In the TLS 1.3 protocol, the key exchange algorithm is omitted. For example, in the cipher suite TLS_AES_128_GCM_SHA256, AES_128_GCM is the bulk encryption algorithm, and SHA256 is the MAC algorithm to be used.

3. What TLS protocols are allowed in the FIPS 140-3 standard?

   TLS 1.3 and TLS 1.2.

4. What TLS cipher suites are allowed in the FIPS 140-3 standard?

   The following suites are allowed for the TLS 1.3 protocol:

   • TLS_AES_128_GCM_SHA256
   • TLS_AES_256_GCM_SHA384

   The following suites are allowed for the TLS 1.2 protocol on Java releases less then Java 21:

   • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
   • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
   • TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
   • TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
   • *1 TLS_DHE_RSA_WITH_AES_256_GCM_SHA384
   • *1 TLS_DHE_RSA_WITH_AES_128_GCM_SHA256
   • TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
   • TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
   • TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
   • TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
   • *1 TLS_DHE_RSA_WITH_AES_256_CBC_SHA256
   • *1 TLS_DHE_RSA_WITH_AES_128_CBC_SHA256
   1. The _DHE_ related ciphers within TLS are allowable. For users of the “FIPS140-3-Weakly-Enforced” profile making use of these ciphers should work without additional configuration. Users of the strict “FIPS140-3” profile will require additional configuration in order to make use of the _DHE_ ciphers listed above. This is not enabled by default since DiffieHellman key agreement is generally not allowable in FIPS 140-3 for universal usage ( only allowed for use with TLS ). In order to make the DHE ciphersuites work, the following crypto services should be enabled. See section Java restricted security mode profiles for further information on how these can be set in specific profiles:

      com.ibm.crypto.plus.provider.OpenJCEPlusFIPS [+ {AlgorithmParameters, DiffieHellman, *}, \
      {KeyAgreement, DiffieHellman, *}, \
      {KeyPairGenerator, DiffieHellman, *}, \
      {KeyFactory, DiffieHellman, *}]

      Applications should then need to ensure that the algorithms such as DiffieHellman are only used under very specific FIPS 140-3 NIST approved circumstances.