8 Jipher Reference Information
Supported Algorithm Strings
The following table lists the algorithm strings and their aliases supported by Jipher. These strings are grouped by their associated engine class.
Table 8-1 Algorithm Strings Supported by Jipher
| Engine | Supported Algorithm Strings and Their Aliases | Notes |
|---|---|---|
AlgorithmParameters |
|
— |
|
|
— | |
|
|
— | |
|
|
— | |
Cipher |
|
— |
|
|
RFC 3394 | |
|
|
RFC 5649 | |
|
|
— | |
|
|
— | |
|
|
PBES2 password-based cipher | |
|
|
— | |
| KDFFoot 2 |
|
HMAC-based KDF as defined in RFC 5869.Foot 2 |
| KEM |
|
The Module-Lattice-Based Key-Encapsulation Mechanism (ML-KEM) as defined in FIPS 203.
This algorithm supports keys with ML-KEM-512, ML-KEM-768, and ML-KEM-1024 parameter sets. |
| KeyAgreement |
|
— |
KeyFactory |
|
— |
|
|
— | |
|
|
— | |
KeyGenerator |
|
— |
|
|
— | |
|
|
These non-standard KeyGenerator algorithms are needed to provide the cryptography required by the SunJSSE provider to support TLSv1.2. | |
KeyPairGenerator |
|
— |
|
|
— | |
|
|
— | |
Mac |
|
— |
MessageDigest |
SHA-1 (SHA, SHA1, 1.3.14.3.2.26, OID.1.3.14.3.2.26
)
|
— |
|
|
— | |
|
|
— | |
SecretKeyFactory |
|
— |
|
|
— | |
|
|
— | |
SecureRandom |
DRBG (SHA1PRNG,
CTRDRBG, CTRDRBG128,
NativePRNG,
NativePRNGNonBlocking)
|
All aliases use the same underlying DRBG algorithm from OpenSSL |
Signature |
|
The Module-Lattice-Based Digital Signature Algorithm (ML-DSA) as defined in FIPS 204.
This algorithm supports keys with ML-DSA-44, ML-DSA-65, and ML-DSA-87 parameter sets. |
|
|
— | |
|
|
— | |
|
|
— | |
|
|
RSA with PKCS1 | |
|
|
— |
Footnote 1 This algorithm is not supported if the FIPS 140 Enforcement Policy is set to FIPS_STRICT.
Footnote 2 KDF service algorithms are only supported when Jipher is run on a Java version that supports the KDF API. See JEP 510
Footnote 3 Only signature verification is supported if the FIPS 140 Enforcement Policy is set to FIPS.
Optionally Supported Non-FIPS 140-3 Allowed Algorithms
The algorithms corresponding to the strings in the following table use the PKCS #12 Key Derivation Function (KDF) as described in Appendix B: Deriving Keys and IVs from Passwords and Salt in RFC 7292: PKCS #12: Personal Information Exchange Syntax v1.1. The PKCS #12 KDF is not allowed by FIPS 140-3. Jipher provides support for these algorithms only if the system property jipher.nonfips.supportPkcs12Kdf is set to true. Support for these algorithms will be removed in a future release of Jipher.
Table 8-2 Algorithm Strings of Optionally Supported Non-FIPS 140-3 Allowed Algorithms
| Engine | Algorithm Strings (and their Aliases) of Optionally Supported Non-FIPS 140-3 Allowed Algorithms |
|---|---|
AlgorithmParameters |
|
Cipher |
|
Mac |
|
SecretKeyFactory |
|
Footnote 4 This algorithm is not supported if the FIPS 140 Enforcement Policy is set to FIPS_STRICT.
On JDK 25 and earlier, the SUN provider’s PKCS12 KeyStore service employs HmacPBE* Mac algorithms for the integrity check when reading KeyStore instances from or writing them to persistent storage. If your application absolutely must load a PKCS12 KeyStore from or store one to persistent storage, then you can set the system property jipher.nonfips.supportPkcs12Kdf to true to configure Jipher to provide support for HmacPBE* Mac algorithms. This setting deviates from the FIPS 140-3 standard.
Keysize Restrictions
Jipher uses the following default key sizes (in bits) and enforces the following restrictions for KeyGenerator and KeyPairGenerator.
KeyGenerator
Jipher honors the
system property jdk.security.defaultKeySize, which enables users to
configure the default key size used by KeyGenerator. The value of this
property is a list of comma-separated entries. Each entry consists of a case-insensitive
algorithm name and the corresponding default key size (in decimal) separated by a
colon.
Table 8-3 KeyGenerator Algorithms and Default Key Sizes
| Algorithm Name | Default Key Size | Restrictions and Comments |
|---|---|---|
| AES | 256 if permitted by the cryptographic policy (see Import Limits on Cryptographic Algorithms), 128 otherwise. | Key size must be equal to 128, 192, or 256. |
| AES_128/<mode>/<padding> | 128 | Key size must be equal to 128. |
| AES_192/<mode>/<padding> | 192 | Key size must be equal to 192. |
| AES_256/<mode>/<padding> | 256 | Key size must be equal to 256. |
| HmacSHA1 | 160 |
Key size must be at least 40 bits. Key sizes that are not a multiple of 8 are increased to the next multiple of 8. |
| HmacSHA224 | 224 |
Key size must be at least 40 bits. Key sizes that are not a multiple of 8 are increased to the next multiple of 8. |
| HmacSHA256 | 256 |
Key size must be at least 40 bits. Key sizes that are not a multiple of 8 are increased to the next multiple of 8. |
| HmacSHA384 | 384 |
Key size must be at least 40 bits. Key sizes that are not a multiple of 8 are increased to the next multiple of 8. |
| HmacSHA512 | 512 |
Key size must be at least 40 bits. Key sizes that are not a multiple of 8 are increased to the next multiple of 8. |
KeyPairGenerator
Jipher honors the system property jdk.security.defaultKeySize, which enables users to configure the default key size used by KeyPairGenerator. The value of this property is a list of comma-separated entries. Each entry consists of a case-insensitive algorithm name and the corresponding default key size (in decimal) separated by a colon.
Table 8-4 KeyPairGenerator Algorithms and Default Key Sizes
| Algorithm Name | Default Key Size | Restrictions and Comments |
|---|---|---|
| DiffieHellman | 3072 |
Key size must be equal to 2048, 3072 or 4096. Algorithm parameter specification must specify an approved FFC Safe-prime group defined in SP 800-56A Rev. 3, "Appendix D: Approved ECC Curves and FFC Safe-prime Groups." |
| EC | 256 |
Key size must be equal to 224, 256, 384, 521. Algorithm parameter specification must specify one the four approved ECC named curves listed in Approved ECC Named Curves and SP 800-56A Rev. 3, "Appendix D: Approved ECC Curves and FFC Safe-prime Groups" defined in RFC 8422: Elliptic Curve Cryptography (ECC) Cipher Suites for Transport Layer Security (TLS) Versions 1.2 and Earlier. |
| RSA and RSASSA-PSS | 3072 |
Key size must be between 2,048 and 15,360 bits. The public exponent length must exceed 16 bits and cannot exceed 256 bits. If the key size exceeds 3072, then the public exponent length cannot exceed 64 bits. |
| ML-KEM | ML-KEM-768 | Parameter set must be one of ML-KEM-512, ML-KEM-768 or ML-KEM-1024. |
| ML-DSA | ML-DSA-65 | Parameter set must be one of ML-DSA-44, ML-DSA-65 or ML-DSA-87. |
Approved ECC Named Curves
| Standard for Efficient Cryptography Group (SECG) Name | NIST | OID |
|---|---|---|
| secp224r1 | P-224 | 1.3.132.0.33 |
| secp256r1 | P-256 | 1.2.840.10045.3.1.7 |
| secp384r1 | P-384 | 1.3.132.0.34 |
| secp521r1 | P-521 | 1.3.132.0.35 |
Supported Elliptic Curve Names
Jipher supports only a fixed set of named (published) elliptic curves. These are NIST-recommended curves based on prime fields.
The following table lists the elliptic curves that are provided by Jipher.
Table 8-5 Supported Elliptic Curve Names
| Elliptic Curve | Object Identifier and Aliases | Aliases |
|---|---|---|
| secp224r1 | 1.3.132.0.33 |
P-224, P224 |
| secp256r1 | 1.2.840.10045.3.1.7 |
P-256, P256,
prime256v1 |
| secp384r1 | 1.3.132.0.34 |
P-384, P384 |
| secp521r1 | 1.3.132.0.35 |
P-521, P521 |
Default Diffie-Hellman Parameters
When generating Diffie-Hellman (DH) key pairs, default DH parameters are selected based on key size. Supported key sizes are 2048, 3072, and 4096.
The default parameters are from RFC 7919: Negotiated Finite Field Diffie-Hellman Ephemeral Parameters for Transport Layer Security.
Table 8-6 Default DH Parameters
| Key Size | Default Parameter |
|---|---|
| 2048 | ffdhe2048 |
| 3072 | ffdhe3072 |
| 4096 | ffdhe4096 |
Sourcing Cryptographically Secure Random Bits
This section describes how the com.oracle.jipher module sources cryptographically secure random bits in accordance with NIST SP 800-90A.
In short, Jipher defers to OpenSSL's FIPS Random Bit Generator (RBG) for Jipher cryptographic operations. A SecureRandom supplied to init, initialize, or newEncapsulator is accepted for Java API compatibility but ignored as a source of random bytes.
SecureRandom.getInstance("DRBG", "JipherJCE") also obtains bytes from the OpenSSL FIPS RBG.
What Happens to a Supplied SecureRandom
For any of the following Java Cryptography API calls to the JipherJCE provider, the SecureRandom argument is ignored as a source of random bytes:
- Cipher.init(..., SecureRandom)
- KeyPairGenerator.initialize(..., SecureRandom)
- Signature.initSign(..., SecureRandom)
- KeyGenerator.init(..., SecureRandom)
- AlgorithmParameterGenerator.init(..., SecureRandom)
- KeyAgreement.init(..., SecureRandom)
- KEM.newEncapsulator(..., SecureRandom)
In the following example, Jipher does not use the argument testRandom:
Signature signature = Signature.getInstance("RSASSA-PSS", "JipherJCE");
...
signature.initSign(privateKey, testRandom);The argument testRandom is ignored. Any random bytes required by the RSA signing operation come from OpenSSL. The same applies whether testRandom is a Jipher SecureRandom, a standard JDK implementation, or a deterministic test double. Do not rely on using a SecureRandom that produces a repeatable deterministic series of bits for application testing. The Java Cryptography API, specifies that API calls that do not accept a SecureRandom argument, but nonetheless require a source of random bytes, obtain randomness
… using the SecureRandom implementation of the highest-priority installed provider as the source of randomness. (If none of the installed providers supply an implementation of SecureRandom, a system-provided source of randomness will be used.)
The JipherJCE provider deviates from this specified behavior. When an API call implemented by JipherJCE requires random bytes and no SecureRandom instance is supplied, it uses an internal OpenSSL Deterministic Random Bit Generator (DRBG) instead of a SecureRandom provided by the highest-priority installed provider.
Motivation for Using OpenSSL's FIPS Random Bit Generator
There are two reasons for Jipher using an OpenSSL DRBG instead of a SecureRandom provided by the highest-priority installed provider:
-
FIPS compliance issues:
-
Approved random bit generators (RBGs) are defined in SP 800-90A: Recommendation for Random Number Generation Using Deterministic Random Bit Generators.
-
The required security strength for RBGs is defined in several NIST documents, including NIST SP 800-133 Rev. 2: Recommendation for Cryptographic Key Generation.
Jipher must guarantee that it only uses a FIPS-approved RBG that provides sufficient security strength.
-
-
Performance issues:
-
Cryptographic functionality provided by JipherJCE classes is, behind the scenes, delivered by the OpenSSL FIPS module.
-
A performance benefit is derived by having OpenSSL use the FIPS module's own native DRBG for all internal operations.
Configuring an OpenSSL algorithm instance to use a specific Java SecureRandom instance as its source of randomness is technically possible. However, we have chosen not to support it at this time, pending a better understanding of the runtime performance implications of developing and maintaining the required bridge.
-
Where Jipher SecureRandom Bytes Come From
Jipher registers one SecureRandom algorithm: DRBG. Its SPI delegates nextBytes and generateSeed to Jipher's Rand.generate, which calls OpenSSL's randBytes at a requested strength of 256 bits. This means that the following code fills bytes using the OpenSSL random subsystem in Jipher's library context:
SecureRandom random = SecureRandom.getInstance("DRBG", "JipherJCE");
random.nextBytes(bytes);Jipher's DRBG algorithm is not a Java-side DRBG with Java-visible state.
Calling random.setSeed(...) is accepted but has no effect. Jipher's SecureRandomSpi.engineSetSeed is intentionally a no-op. In particular, seeding a Jipher SecureRandom cannot make either that instance or an OpenSSL-backed Jipher operation reproducible.
OpenSSL DRBG
OpenSSL internally manages a DRBG hierarchy used by operations requiring a source of randomness. The configured DRBG algorithm will be one of the following, configured with 256-bit security strength:
- CTR-DRBG
- HASH-DRBG
- HMAC-DRBG
OpenSSL uses a per-thread DRBG seeded from a global DRBG. Entropy for the global DRBG is obtained from the operating system and both global and per-thread DRBGs are automatically reseeded according to configured call-count and time intervals. These are OpenSSL configuration settings, not per-instance Java SecureRandom settings.
See the OpenSSL RAND and OSSL_PROVIDER-FIPS man pages for more information.
Unsupported Java DRBG Operations
Jipher does not bridge Java's post-JDK-8 parameterized SecureRandom APIs to OpenSSL.
The following table lists Java DRBG operations that aren't supported by Jipher and describes how Jipher behaves when they are called.
Table 8-7 Java DRBG Operations Not Supported by Jipher
| Operation | Jipher Behavior |
|---|---|
SecureRandom.getInstance("DRBG", params, "JipherJCE") |
Throws NoSuchAlgorithmException. Jipher's SPI cannot be constructed with parameters. |
random.getParameters() |
Returns null.
|
random.nextBytes(bytes, params) |
Throws UnsupportedOperationException. |
random.reseed() |
Throws UnsupportedOperationException. |
random.reseed(params) |
Throws UnsupportedOperationException. |
Calling SecureRandom.getInstance(String algorithm, SecureRandomParameters params) without naming Jipher may select another installed provider that supports the requested parameters. That instance remains a Java-side random source. Passing it to a Jipher service still does not alter the OpenSSL source used by that service.
Jipher Development and Test Guidance with RBGs
- Use Jipher's SecureRandom when an application directly needs random bytes produced by Jipher's OpenSSL-backed random subsystem.
- It is preferable to use JCA initialization APIs that do not specify a SecureRandom when possible instead of passing
nullor a subsequently ignored object. - Do not use a deterministic SecureRandom injection to make a Jipher operation repeatable. Assert externally observable properties instead, or use a dedicated Jipher/OpenSSL test facility if one is provided.