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 .NET 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, through System.Security.Cryptography, and refuses what that module doesn’t approve with a typed status. The bundled BouncyCastle and Botan libraries 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 which operations are refused.
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. The SDK reads it through BCryptGetFipsAlgorithmMode, and on .NET Framework through CryptoConfig.AllowOnlyFipsAlgorithms as well.
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
Register the SDK license before running document operations. For setup details, refer to the getting started with .NET SDK guide.
using GdPicture14;
LicenseManager licence = new LicenseManager();licence.RegisterKEY(""); // Set your license keyForce and read the mode from code
Detection is the default (FipsMode.Auto). GdPictureDocumentUtilities.SetFipsMode 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 mode set in code takes precedence over the NUTRIENT_FIPS_MODE variable. GetFipsMode reads the mode back, and GetCryptoBackend shows which library the SDK selected: Platform, the operating system’s module, when FIPS mode is on.
GdPictureStatus modeStatus = GdPictureDocumentUtilities.SetFipsMode(FipsMode.On);if (modeStatus != GdPictureStatus.OK){ Console.Error.WriteLine($"Setting FIPS mode failed: {modeStatus}"); Environment.Exit(1);}
Console.WriteLine($"FIPS mode: {GdPictureDocumentUtilities.GetFipsMode()}");Console.WriteLine($"Crypto backend: {GdPictureDocumentUtilities.GetCryptoBackend()}");On a host in FIPS mode, leave SetFipsMode out: GetFipsMode() returns Auto and GetCryptoBackend() returns Platform all the same.
Work with approved algorithms
AES-256 encryption and SHA-2 signatures run as usual. Encrypting a document with 256-bit AES (PDF revision 6) writes the file with the module’s AES, SHA-256 and random generator:
using GdPicturePDF pdf = new GdPicturePDF();GdPictureStatus loadStatus = pdf.LoadFromFile(@"input.pdf");if (loadStatus != GdPictureStatus.OK){ Console.Error.WriteLine($"Loading PDF failed: {loadStatus}"); Environment.Exit(1);}
GdPictureStatus saveStatus = pdf.SaveToFile(@"output.pdf", PdfEncryption.PdfEncryption256BitAES2, "user", "owner", true, false, false, true, true, true, true, true);if (saveStatus != GdPictureStatus.OK){ Console.Error.WriteLine($"Saving the AES-256 encrypted PDF failed: {saveStatus}"); Environment.Exit(1);}Console.WriteLine("Saved output.pdf with 256-bit AES encryption.");See what FIPS mode refuses
Two kinds of refusal exist, and both return a status instead of falling back to another library.
Selecting a library other than the operating system’s returns FipsPolicyViolation:
GdPictureStatus backendStatus = GdPictureDocumentUtilities.SetCryptoBackend(CryptoBackend.BouncyCastle);Console.WriteLine($"Selecting BouncyCastle in FIPS mode: {backendStatus}");if (backendStatus != GdPictureStatus.FipsPolicyViolation){ Console.Error.WriteLine("Expected FipsPolicyViolation."); Environment.Exit(1);}Writing a document with an algorithm the module doesn’t approve returns NotImplemented. The operating system’s library has no RC4, and the PDF security handler of revisions 2 to 4 computes its password entries with RC4 and MD5, so 40-bit RC4, 128-bit RC4 and 128-bit AES are all refused; so is opening a document encrypted that way, with PdfCanNotBeDecrypted:
GdPictureStatus rc4Status = pdf.SaveToFile(@"output-rc4.pdf", PdfEncryption.PdfEncryption128BitRC4, "user", "owner", true, false, false, true, true, true, true, true);Console.WriteLine($"Saving with 128-bit RC4 in FIPS mode: {rc4Status}");if (rc4Status != GdPictureStatus.NotImplemented){ Console.Error.WriteLine("Expected NotImplemented."); Environment.Exit(1);}pdf.CloseDocument();The other refusals follow the same pattern:
| Operation | Status |
|---|---|
Signing with SHA-1 (SetSignatureHash(PdfSignatureHash.SHA1)) | CertificateUnsupportedHashAlgorithm |
| Verifying an existing SHA-1 or MD5 signature that the module refuses | GetSignatureInfo returns CertificateUnsupportedHashAlgorithm with the signer’s details, instead of reporting an invalid signature |
| Loading a PKCS#12 file encrypted with 3DES or RC2 when the module refuses those ciphers | CertificateUnsupportedHashAlgorithm; export the certificate again with AES-256 |
Exporting a signer certificate as PKCS#12 (ExportCertToFile, ExportCertToStream), whose MAC key derivation (RFC 7292) no module approves | CertificateUnsupportedHashAlgorithm on every host in FIPS mode |
| Opening a certificate-encrypted PDF whose file key uses RSA PKCS#1 v1.5 when the module refuses that padding (OpenSSL’s FIPS provider does) | NotImplemented from SetCertificate |
Which of these occur depends on the host’s module. OpenSSL’s FIPS provider refuses MD5, SHA-1 signature verification, 3DES, RC2 and RSA PKCS#1 v1.5 key transport. Windows CNG computes MD5, verifies SHA-1 and decrypts PKCS#1 v1.5 under the policy, so on Windows only the SDK’s own refusals (library selection, RC4-based encryption, SHA-1 signing) 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 the product default library again. This leaves the FIPS boundary and is the deployment’s decision, not the SDK’s.
Conclusion
This guide puts the SDK in FIPS mode, shows that AES-256 encryption runs in the operating system’s module, and shows the typed refusals for a bundled library and for RC4. For the full statement of what runs where, the algorithms refused on each host, and how to verify a host, refer to the FIPS 140-3 statement in the SDK repository (docs/security/FIPS-140-3.md).