Install and verify an OpenSSL FIPS configuration

You will generate a configuration file that records the integrity MAC and self-test status for an OpenSSL FIPS provider, then verify that file against the provider module. Allow about 15 minutes if the FIPS module is already installed and you know where the configuration belongs. This guide describes the openssl-fipsinstall(1ssl) manual installed with the Debian openssl package, version 3.0.13 on this machine.

1. Check the executable and its version

The command is a subcommand of openssl, not necessarily a separate executable. Check which installation your shell will use before trusting any output. A shell can find a Homebrew or locally built OpenSSL before the packaged /usr/bin/openssl.

$ type -a openssl
$ openssl version -a
$ openssl fipsinstall -help

The local manual is for OpenSSL 3.0.13, while the executable selected by this shell reports OpenSSL 3.6.1. That mismatch matters: newer builds can show options that are absent from the local manual. Follow the manual that matches the executable used by your service. If the versions do not match, use an explicit path such as /usr/bin/openssl for both your checks and the installation command.

2. Locate the FIPS provider module

You need the FIPS provider shared object, commonly named fips.so, and permission to read it. The -module path is stored in the generated configuration and takes precedence over OPENSSL_MODULES when the provider is activated. Do not guess this path or copy a module from a different OpenSSL build.

$ MODULE=/path/to/your/fips.so
$ test -r "$MODULE" && printf 'readable: %s\n' "$MODULE"
$ file "$MODULE"

Replace the placeholder with the path supplied by your OpenSSL build or operating system package. This guide cannot provide a working module path for every distribution, and the FIPS provider is not present in every OpenSSL installation.

3. Generate the provider configuration

Choose a new output path first. The command calculates a MAC for the module, runs the FIPS self tests, and writes the configuration data to -out. The documented defaults are provider name fips, section name fips_sect, HMAC as the MAC algorithm, and SHA-256 as the HMAC digest.

$ CONFIG=/path/to/fips.cnf
$ openssl fipsinstall \
    -module "$MODULE" \
    -out "$CONFIG" \
    -provider_name fips \
    -section_name fips_sect

Exact self-test messages vary by build. A successful exit status and a newly written configuration file are the useful checks. If you need a different MAC algorithm, list the algorithms supported by this executable before choosing one:

$ openssl list -mac-algorithms

Writing under a system directory may require sudo; generating the file in a user-owned working directory does not. If the destination already exists, choose another name or back it up first. Shell redirection is not involved here, but -out can still replace an existing file.

4. Verify the generated file

Verification reads the configuration and recalculates the module information. It requires both -in and -module. Use the same module path and provider name used during generation.

$ openssl fipsinstall \
    -module "$MODULE" \
    -in "$CONFIG" \
    -provider_name fips \
    -section_name fips_sect \
    -verify

Use the exit status as the automation signal. A zero status means verification completed successfully; a non-zero status needs investigation:

$ if openssl fipsinstall -module "$MODULE" -in "$CONFIG" -provider_name fips -verify; then
>     echo 'FIPS configuration verified'
> else
>     echo 'FIPS configuration failed verification' >&2
>     exit 1
> fi

A failure usually means that the module changed, the configuration was edited, the wrong provider name or section was selected, or the command is using a different OpenSSL installation. Compare type -a openssl, the module path and the configuration path before regenerating anything.

5. Test a parent configuration when required

Use -config only when you want to test that a FIPS provider can load from a parent OpenSSL configuration. With this option, all other options are ignored. The parent configuration must already include the extra data generated by an earlier fipsinstall call and must define the provider section expected by your setup.

$ export OPENSSL_CONF_INCLUDE=/path/to/config-directory
$ export OPENSSL_MODULES=/path/to/provider-directory
$ openssl fipsinstall -config /path/to/default.cnf

Use temporary shell exports when diagnosing a deployment. They disappear when the shell exits. Do not add them to a service unit or global profile until the service's OpenSSL version, provider path and configuration path have been reviewed.

6. Keep specialised options out of routine installs

-self_test_onload omits the two status fields so the known-answer tests run every time the module loads. The manual identifies this as useful for cross-compiling, where tests must run on each target machine. It is not a harmless performance switch for an ordinary installation.

-no_conditional_errors permits the module to avoid entering its error state after a conditional self-test failure, and -no_security_checks disables run-time security checks. Both weaken normal safeguards and can affect compliance. Use them only when your approved security policy explicitly requires them. Likewise, -corrupt_desc and -corrupt_type are test controls for deliberately exercising self-test failures, not repair options.

For quiet automation, -quiet suppresses pass and fail messages and implies -noout. Keep normal output during an initial installation so a human can see the self-test result; use -quiet only when the calling script records the exit status and its own diagnostics.