7 Jipher Diagnostics

Confirming That a Java Application Is Using Jipher

If you set the system property java.security.debug to jipher, then Jipher will print additional information. The output is similar to the following:

jipher: FIPS Provider detected OpenSSL FIPS Provider
jipher: FIPS Provider version 3.5.7
jipher: FIPS Provider major version 3
jipher: FIPS Provider minor version 5
jipher: Setting FIPS enforcement policy = FIPS
jipher: Checking KEYGEN RSA size against FIPS Policy (FIPS)...

See The java.security.debug System Property in Java Platform, Standard Edition Security Developer's Guide for more information.

Keeping Track of Security Provider Usage with the jdk.SecurityProviderService Java Flight Recorder (JFR) Event

In JDK 20 and later, the Java Flight Recorder (JFR) event jdk.SecurityProviderService records the details of java.security.Provider.getService(String type, String algorithm) calls. This event contains the following fields:

Table 7-1 JFR Event jdk.SecurityProviderService Fields

Field Name	Description
type	Type of service
algorithm	Algorithm name
provider	Security provider

You can use the JFR event jdk.SecurityProviderService to confirm that a Java application is using Jipher. This JFR event is disabled by default. You can enable it through JFR configuration files or standard JFR options.

Reporting the Enforcement of FIPS 140-3 Restrictions

When enforcing FIPS 140-3 restrictions, Jipher throws an InvalidParameterException if directed to generate the following:

• A SecretKey or KeyPair with a security strength of less than 112 bits

• A Diffie-Hellman KeyPair using domain parameters that are not a FIPS 140-3 approved safe prime group (see "Appendix D: Approved ECC Curves and FFC Safe-prime Groups" in NIST SP 800-56A Rev. 3: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography)

• An elliptic curve KeyPair using a curve that is not a FIPS 140-3 approved secp curve (see again "Appendix D: Approved ECC Curves and FFC Safe-prime Groups").

Similarly, Jipher throws a ProviderException if directed to use the following:

• A KeyPair with a security strength of less than 80 bits to process secured data, for example, to verify a signature or decrypt cipher text
• A SecretKey or KeyPair with a security strength of less than 112 bits to secure data, for example, to generate a digital signature or encrypt plaintext
• SHA-1 to generate a signature
• A DSA KeyPair that does not use domain parameters allowed by FIPS 140-3 (listed previously)

See "Table 2: Comparable security strengths of symmetric block cipher and asymmetric-key algorithms" in NIST SP 800-57 Part 1 Rev. 5: Recommendation for Key Management: Part 1 – General for the estimated security strengths of specific algorithms and key lengths.

Reporting Misconfiguration

If Jipher is unable to load its native library dependencies at run time, it throws the following:

java.security.ProviderException: OpenSSL is not available

Determine the failure's root cause from the final Throwable in the chain of exceptions:

Throwable	Message	Meaning
java.lang.UnsatisfiedLinkError	Can't load library: <path to>/(lib)jipherffi.<ext>	Jipher is unable to load its JNI native library. This happens if the file is missing. See jipher.jniadapter.jipherffi.dir in Table 3-2.
	<path to>/(lib)jipherffi.<ext>: Access is denied	Jipher is unable to load its JNI native library. This occurs if the file is not readable or cannot be run by the operating system user running the JVM process. See jipher.jniadapter.jipherffi.dir in Table 3-2.
com.oracle.jipher.internal.openssl.OpenSslException	OpenSSL crypto library path not found	Jipher is unable to load the OpenSSL cryptography library. This occurs if the file is missing, unreadable, or is not executable by the operating system user running the JVM process. See jipher.openssl.dir in Table 3-2.
	FIPS provider is not available	Jipher is unable to load the OpenSSL FIPS provider. This occurs if the file is missing, unreadable, or is not executable by the operating system user running the JVM process. It also occurs if the instance of the OpenSSL FIPS module that Jipher attempts to load is inconsistent with the jipher.fips.deactivateSecurityPatches system property setting. If jipher.fips.deactivateSecurityPatches is not set to true and Jipher attempts to load the certified OpenSSL module, then an OpenSslException is thrown. If jipher.fips.deactivateSecurityPatches is set to true and Jipher attempts to load the patched OpenSSL module, then an OpenSslException is thrown. See jipher.openssl.dir and jipher.fips.deactivateSecurityPatches in Table 3-2.

Reporting Abnormal Operation in OpenSSL Native Code

An error condition that arises in OpenSSL native code is reported to the application through the following:

• A java.lang.Error, such as java.lang.OutOfMemoryError
• A java.lang.RuntimeException, either java.lang.ArrayIndexOutOfBoundsException or java.lang.IllegalArgumentException, indicating a programming error
• A ProviderException whose chained cause is an internal OpenSslException whose detail message describes the OpenSSL error stack for use in debugging and troubleshooting