---
title: "Run on a FIPS-enabled host | Nutrient Java SDK"
canonical_url: "https://www.nutrient.io/guides/java/security/run-on-a-fips-enabled-host/"
md_url: "https://www.nutrient.io/guides/java/security/run-on-a-fips-enabled-host.md"
last_updated: "2026-11-20T00:00:00.000Z"
description: "Learn how Nutrient Java SDK detects FIPS mode and runs document cryptography in the host's FIPS 140-3 validated module."
---

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](https://www.nutrient.io/downloads/samples/java/run-on-a-fips-enabled-host.zip)

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

```bash

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:

```ini

# 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

```

```bash

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:

```bash

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

```powershell

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:

```java

package io.nutrient.Sample;

```

Import the SDK classes the sample uses:

```java

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.

```java

    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:

```java

    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:

```text

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:

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

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](https://www.nutrient.io/downloads/samples/java/run-on-a-fips-enabled-host.zip) to run the example locally.
---

## Related pages

- [Nutrient Java SDK security guides](/guides/java/security.md)

