Run on a FIPS-enabled host
Government and regulated deployments often run on hosts in FIPS mode: Amazon Linux 2023 or RHEL 9 with the OpenSSL FIPS provider, or Windows with the FIPS algorithm policy. On such a host, every cryptographic operation an application performs must run inside the host’s FIPS 140-3 validated module, and algorithms the module doesn’t approve must be refused rather than computed elsewhere.
Nutrient Java SDK has a FIPS mode for this. In FIPS mode the SDK runs all of its document cryptography (digital signatures, timestamps, PDF password and certificate encryption) in the operating system’s validated module and refuses what that module doesn’t approve with a typed exception. The bundled Botan library can’t be selected. The SDK itself holds no FIPS certificate; the host module’s certificate is the one that applies.
This guide shows how to put a host in FIPS mode, how the SDK detects it, how to force or read the mode from code, and what the SDK refuses.
Download samplePrepare the host
The SDK detects FIPS mode from the host. Nothing in the SDK’s configuration is needed on a host that’s set up as follows.
Amazon Linux 2023
Amazon Linux 2023 ships two OpenSSL FIPS provider packages. The latest one tracks upstream fixes; the certified one is the module with a CMVP certificate. Swap to the certified one, then enable FIPS mode in the kernel:
sudo dnf -y install opensslsudo dnf -y swap openssl-fips-provider-latest openssl-fips-provider-certifiedsudo dnf -y install crypto-policies-scriptssudo fips-mode-setup --enablesudo rebootAfter the reboot, cat /proc/sys/crypto/fips_enabled prints 1. That’s the flag the SDK reads.
In a container the kernel flag doesn’t exist, so the SDK can’t detect FIPS mode there. Run the container with an OpenSSL configuration that activates only the fips and base providers, and force the SDK’s mode with the NUTRIENT_FIPS_MODE environment variable:
# fips-only.cnfopenssl_conf = openssl_init
[openssl_init]providers = provider_sectalg_section = algorithm_sect
[provider_sect]fips = fips_sectbase = base_sect
[fips_sect]activate = 1
[base_sect]activate = 1
[algorithm_sect]default_properties = fips=yesexport OPENSSL_CONF=/etc/fips-only.cnfexport NUTRIENT_FIPS_MODE=OnRed Hat Enterprise Linux 9
RHEL 9 enables FIPS mode with one command and a reboot:
sudo fips-mode-setup --enablesudo rebootfips-mode-setup --checkThis switches the kernel flag and the system-wide crypto policy. Nutrient documents this recipe from Red Hat’s instructions; the SDK’s test suite runs on Amazon Linux 2023.
Windows
Set the FIPS algorithm policy, which is the Group Policy setting “System cryptography: Use FIPS compliant algorithms for encryption, hashing, and signing”:
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy" /v Enabled /t REG_DWORD /d 1 /fProcesses started after the change see the policy.
macOS
macOS has no FIPS mode the SDK detects. Forcing the mode on selects the operating system’s library, as on the other platforms, but Nutrient makes no claim about Apple’s libraries.
Prepare the project
Specify a package name and create a new class:
package io.nutrient.Sample;Import the SDK classes the sample uses:
import io.nutrient.sdk.Document;import io.nutrient.sdk.enums.FipsMode;import io.nutrient.sdk.exceptions.NutrientException;import io.nutrient.sdk.settings.SdkSettings;
public class RunOnAFipsEnabledHost {Force and read the mode from code
Detection is the default (FipsMode.Auto). setFipsMode on the SDK-wide crypto settings forces the mode on or off for the whole process, which is useful when the host runs in a container or when a test must behave as a FIPS host does. A value set in code takes precedence over the NUTRIENT_FIPS_MODE variable. getBackend on the same settings returns the configured preference (Botan by default), not the library the SDK resolved: in FIPS mode the SDK selects the operating system’s module whatever that value says. To see the resolved library, read the SDK log: the first cryptographic operation writes Crypto backend: Platform (System.Security.Cryptography on ...); FIPS mode on (set in code).
FIPS mode is a property of the process, so set it on SdkSettings; a value set on a document’s settings isn’t read.
public static void main(String[] args) { SdkSettings.getCryptoSettings().setFipsMode(FipsMode.On); System.out.println("FIPS mode: " + SdkSettings.getCryptoSettings().getFipsMode());
try { exportInFipsMode(); } catch (NutrientException e) { System.err.println("Nutrient SDK Error: " + e.getMessage()); System.exit(1); } }On a host in FIPS mode, leave the setFipsMode call out: the mode stays Auto and the SDK selects the operating system’s library all the same.
Work with approved algorithms
Open a document and export it. Every digest and cipher the export needs runs in the module. The method declares throws NutrientException, so main reports a failure at the call site:
private static void exportInFipsMode() throws NutrientException { try (Document document = Document.open("input.pdf")) { document.exportAsPdf("output.pdf"); System.out.println("Exported output.pdf in FIPS mode."); } }}What FIPS mode refuses
Selecting the bundled Botan library while FIPS mode is on throws FipsPolicyException, a NutrientException whose message names the refused selection and the setting that made it. The SDK never falls back to another library. The sample above doesn’t trigger it; this is what a program that calls settings.getCryptoSettings().setBackend(CryptoBackend.Botan) on a DocumentSettings and opens a document with those settings sees:
FipsPolicyException: The Botan crypto backend was selected while FIPS mode is on (set in code).FIPS mode runs every cryptographic operation in the operating system's validated module: selectthe Platform backend, or turn FIPS mode off (NUTRIENT_FIPS_MODE=Off or the product's FIPS modesetting). The SDK selects the backend through CryptoSettings.Backend and FIPS mode throughCryptoSettings.FipsMode.Catch FipsPolicyException before the general NutrientException where your code selects a library.
The other refusals follow the same pattern and throw a NutrientException that carries the status:
| Operation | What happens |
|---|---|
| Opening a PDF encrypted with 40-bit RC4, 128-bit RC4 or 128-bit AES (PDF revisions 2 to 4, whose password entries use RC4 and MD5) | PdfLoadException: the document is encrypted with an algorithm the selected crypto backend doesn’t provide |
| Verifying an existing SHA-1 or MD5 signature that the module refuses | The signature is reported as refused, not as invalid |
| Loading a PKCS#12 file encrypted with 3DES or RC2 when the module refuses those ciphers | PdfSigningException; export the certificate again with AES-256 |
Which of these occur depends on the host’s module. OpenSSL’s FIPS provider refuses MD5, SHA-1 signature verification, 3DES and RC2. Windows CNG computes MD5 and verifies SHA-1 under the policy, so on Windows only the SDK’s own refusals (library selection and RC4-based encryption) apply.
Turn the mode off for legacy documents
A process that must open RC4-encrypted documents on a FIPS host can set NUTRIENT_FIPS_MODE=Off or call setFipsMode(FipsMode.Off). The SDK then runs on Botan, its default library, again. This leaves the FIPS boundary and is the deployment’s decision, not the SDK’s.
Summary
Running the SDK on a FIPS host takes three steps:
- Put the host in FIPS mode, or set
OPENSSL_CONFandNUTRIENT_FIPS_MODE=Onin a container. - Leave the FIPS mode setting at
Auto, or set it toOnto force the mode. - Catch
NutrientExceptionaround document operations, andFipsPolicyExceptionwherever your code selects a library.
You can download this sample package to run the example locally.