This HTML page is not optimized for LLM or AI agent consumption. Fetch the Markdown version instead: /guides/java/security/run-on-a-fips-enabled-host.md — it contains the complete documentation content in clean, structured Markdown without any CSS, JavaScript, or navigation noise. Run on a FIPS-enabled host | Nutrient Java SDK

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 sample

Prepare 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:

Terminal window
sudo dnf -y install openssl
sudo dnf -y swap openssl-fips-provider-latest openssl-fips-provider-certified
sudo dnf -y install crypto-policies-scripts
sudo fips-mode-setup --enable
sudo reboot

After 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.cnf
openssl_conf = openssl_init
[openssl_init]
providers = provider_sect
alg_section = algorithm_sect
[provider_sect]
fips = fips_sect
base = base_sect
[fips_sect]
activate = 1
[base_sect]
activate = 1
[algorithm_sect]
default_properties = fips=yes
Terminal window
export OPENSSL_CONF=/etc/fips-only.cnf
export NUTRIENT_FIPS_MODE=On

Red Hat Enterprise Linux 9

RHEL 9 enables FIPS mode with one command and a reboot:

Terminal window
sudo fips-mode-setup --enable
sudo reboot
fips-mode-setup --check

This 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”:

Terminal window
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Lsa\FipsAlgorithmPolicy" /v Enabled /t REG_DWORD /d 1 /f

Processes 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: select
the Platform backend, or turn FIPS mode off (NUTRIENT_FIPS_MODE=Off or the product's FIPS mode
setting). The SDK selects the backend through CryptoSettings.Backend and FIPS mode through
CryptoSettings.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:

OperationWhat 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 refusesThe signature is reported as refused, not as invalid
Loading a PKCS#12 file encrypted with 3DES or RC2 when the module refuses those ciphersPdfSigningException; 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:

  1. Put the host in FIPS mode, or set OPENSSL_CONF and NUTRIENT_FIPS_MODE=On in a container.
  2. Leave the FIPS mode setting at Auto, or set it to On to force the mode.
  3. Catch NutrientException around document operations, and FipsPolicyException wherever your code selects a library.

You can download this sample package to run the example locally.