OPENSSL-FIPSINSTALL(1SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💖 OPENSSL-FIPSINSTALL 💖 (that's openssl-fipsinstall, from the 1SSL manual, bestie)

✨ NAME ✨

openssl-fipsinstall — perform FIPS configuration installation 🛠️

🌸 SYNOPSIS 🌸

openssl fipsinstall [-help] [-in configfilename] [-out configfilename]
[-module modulefilename] [-provider_name providername] [-section_name
sectionname] [-verify] [-mac_name macname] [-macopt nm:v] [-noout]
[-quiet] [-pedantic] [-no_conditional_errors] [-no_security_checks]
[-hmac_key_check] [-kmac_key_check] [-ems_check]
[-no_drbg_truncated_digests] [-signature_digest_check]
[-hkdf_digest_check] [-tls13_kdf_digest_check] [-tls1_prf_digest_check]
[-sshkdf_digest_check] [-sskdf_digest_check] [-x963kdf_digest_check]
[-dsa_sign_disabled] [-no_pbkdf2_lower_bound_check] [-no_short_mac]
[-tdes_encrypt_disabled] [-rsa_pkcs15_padding_disabled]
[-rsa_pss_saltlen_check] [-rsa_sign_x931_disabled] [-hkdf_key_check]
[-kbkdf_key_check] [-tls13_kdf_key_check] [-tls1_prf_key_check]
[-sshkdf_key_check] [-sskdf_key_check] [-x963kdf_key_check]
[-x942kdf_key_check] [-ecdh_cofactor_check] [-self_test_onload]
[-self_test_oninstall] [-corrupt_desc selftest_description]
[-corrupt_type selftest_type] [-config parent_config] [-defer_tests]

🦋 DESCRIPTION 🦋

Okay so, plot twist, this command is literally the one that generates a FIPS module configuration file. 🎀 You run it, it makes the file, and then every single time a FIPS module gets loaded, that file is right there handing data over to the FIPS module's self tests. Iconic, honestly.

The FIPS module always verifies its MAC. But it only optionally needs to run the KAT's once, at installation. So like… lowkey one-and-done energy. 😌

The generated configuration file is made of these lil pieces:

  • A MAC of the FIPS module file. 🔐
  • A test status indicator. ✨ This one tells you whether the Known Answer Self Tests (KAT's) have successfully run. (Living for the recap.)
  • A MAC of the status indicator. 🔏
  • A control for conditional self tests errors. 😬 By default, if a continuous test (e.g a key pair test) fails, then the FIPS module enters an error state, and no services or cryptographic algorithms will be able to be accessed after this point. The default value of '1' is what makes the fips module error state get entered. If the value is '0' then the module error state will not be entered. But heads up: regardless of whether the error state is entered or not, the current operation (e.g. key generation) will return an error. And if the module error state is not entered, the user is the one responsible for retrying the operation. So that's on you, babe. 💅
  • A control to indicate whether run-time security checks are done. 🕵️♀️ This one says whether run-time checks related to enforcement of security parameters — like minimum security strength of keys and approved curve names — are used. The default value of '1' will perform the checks. If the value is '0' the checks are not performed and FIPS compliance must be done by procedures documented in the relevant Security Policy. 📜

This file is described in fips_config(5). 📖

✨ OPTIONS ✨

okay bestie, this is the part where we go through EVERY. SINGLE. FLAG. one by one, no skimming, no skipping 🫶 every option is iconic in its own way, let's get into it 💅

  • -help — prints a usage message. that's it, that's the whole vibe, a little "hey here's how to use me" moment 🌸
  • -module filename — the filename of the FIPS module you wanna run an integrity check on 🦋 the path you hand over in filename is what gets used to load the module when it's activated, and it overrides the environment variable OPENSSL_MODULES. so yeah, this one wins the argument.
  • -out configfilename — filename where the configuration data gets written out to 📝 default is standard output, so if you don't say anything, it just spills into your terminal like a group chat.
  • -in configfilename — input filename to load configuration data from. you MUST use this if you're using the -verify option — they're a package deal, fr fr 🎀
  • -verify — verify that the input configuration file actually contains the correct information ✅ it's giving auditor energy.
  • -provider_name providername — the name of the provider inside the configuration file. default value is "fips". no cap.
  • -section_name sectionname — the name of the section inside the configuration file. default value is "fips_sect" 💖
  • -mac_name name — specifies the name of a supported MAC algorithm that's gonna get used. which MAC mechanisms you actually have available depends on the options used when building OpenSSL 🌈 to see the list of supported MAC's, run the command openssl list -mac-algorithms. the default is HMAC.
  • -macopt nm:v — passes options to the MAC algorithm. there's a comprehensive list of controls over in the EVP_MAC implementation documentation 📚 the common control strings used for this command are:
    • key:string — specifies the MAC key as an alphanumeric string (use this if the key contains printable characters only). the string length has to conform to any restrictions of the MAC algorithm. a key must be specified for every MAC algorithm 🔑 if no key is provided, the default that was specified when OpenSSL was configured is used.
    • hexkey:string — specifies the MAC key in hexadecimal form (two hex digits per byte). the key length has to conform to any restrictions of the MAC algorithm. a key must be specified for every MAC algorithm. if no key is provided, the default that was specified when OpenSSL was configured is used.
    • digest:string — used by HMAC as an alphanumeric string (use this if the key contains printable characters only). the string length has to conform to any restrictions of the MAC algorithm. to see the list of supported digests, use the command openssl list -digest-commands. the default digest is SHA-256 ✨
  • -noout — disables logging of the self tests. shhh, quiet mode incoming 🤫
  • -pedantic — configures the module so it's strictly FIPS compliant rather than being backwards compatible 🚨 this enables conditional errors, security checks etc. note that any previous configuration options get overwritten and any subsequent configuration options that violate FIPS compliance will result in an error. it's giving strict teacher energy, and honestly? valid.
  • -no_conditional_errors — configures the module to not enter an error state if a conditional self test fails as described above 🙈
  • -no_security_checks — configures the module to not perform run-time security checks as described above. enabling the configuration option "no-fips-securitychecks" provides another way to turn off the check at compile time 👀
  • -ems_check — configures the module to enable a run-time Extended Master Secret (EMS) check when using the TLS1_PRF KDF algorithm. this check is disabled by default ⭐ see RFC 7627 for information related to EMS.
  • -no_short_mac — configures the module to not allow short MAC outputs. see SP 800-185 8.4.2 and FIPS 140-3 ID C.D for details.
  • -hmac_key_check — configures the module to not allow small key sizes when using HMAC. see SP 800-131Ar2 for details 🔍
  • -kmac_key_check — configures the module to not allow small key sizes when using KMAC. see SP 800-131Ar2 for details 🔍
  • -no_drbg_truncated_digests — configures the module to not allow truncated digests to be used with Hash and HMAC DRBGs. see FIPS 140-3 IG D.R for details.
  • -signature_digest_check — configures the module to enforce signature algorithms to use digests that are explicitly permitted by the various standards ✅
  • -hkdf_digest_check — this option is deprecated 💀 (still here for the lore, bestie)
  • -tls13_kdf_digest_check — configures the module to enable a run-time digest check when deriving a key by TLS13 KDF. see RFC 8446 for details 🔐
  • -tls1_prf_digest_check — configures the module to enable a run-time digest check when deriving a key by TLS_PRF. see NIST SP 800-135r1 for details.
  • -sshkdf_digest_check — configures the module to enable a run-time digest check when deriving a key by SSHKDF. see NIST SP 800-135r1 for details.
  • -sskdf_digest_check — this option is deprecated 💀
  • -x963kdf_digest_check — configures the module to enable a run-time digest check when deriving a key by X963KDF. see NIST SP 800-131Ar2 for details.
  • -dsa_sign_disabled — configures the module to not allow DSA signing (DSA signature verification is still allowed tho 🫶). see FIPS 140-3 IG C.K for details.
  • -tdes_encrypt_disabled — configures the module to not allow Triple-DES encryption. Triple-DES decryption is still allowed, for legacy purposes 👵 see SP800-131Ar2 for details.
  • -rsa_pkcs15_padding_disabled — configures the module to not allow PKCS#1 version 1.5 padding to be used with RSA for key transport and key agreement. see NIST's SP 800-131A Revision 2 for details.
  • -rsa_pss_saltlen_check — configures the module to enable a run-time salt length check when generating or verifying a RSA-PSS signature 🧂 see FIPS 186-5 5.4 (g) for details.
  • -rsa_sign_x931_disabled — configures the module to not allow X9.31 padding to be used when signing with RSA. see FIPS 140-3 IG C.K for details.
  • -hkdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by HKDF. see NIST SP 800-131Ar2 for details.
  • -kbkdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by KBKDF. see NIST SP 800-131Ar2 for details.
  • -tls13_kdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by TLS13 KDF. see NIST SP 800-131Ar2 for details.
  • -tls1_prf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by TLS_PRF. see NIST SP 800-131Ar2 for details.
  • -sshkdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by SSHKDF. see NIST SP 800-131Ar2 for details.
  • -sskdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by SSKDF. see NIST SP 800-131Ar2 for details.
  • -x963kdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by X963KDF. see NIST SP 800-131Ar2 for details.
  • -x942kdf_key_check — configures the module to enable a run-time short key-derivation key check when deriving a key by X942KDF. see NIST SP 800-131Ar2 for details.
  • -no_pbkdf2_lower_bound_check — configures the module to not perform a run-time lower bound check for PBKDF2. see NIST SP 800-132 for details.
  • -ecdh_cofactor_check — configures the module to enable a run-time check that ECDH uses the EC curve's cofactor value when deriving a key 🔑 this only affects the 'B' and 'K' curves. see SP 800-56A r3 Section 5.7.1.2 for details.
  • -self_test_onload — do not write the two fields related to the "test status indicator" and "MAC status indicator" to the output configuration file 📄 without these fields the self tests KATS will run each time the module is loaded. this option could be used for cross compiling, since the self tests need to run at least once on each target machine 🖥️ once the self tests have run on the target machine, the user could possibly then add the 2 fields into the configuration using some other mechanism. this option defaults to 0 for any OpenSSL FIPS 140-2 provider (OpenSSL 3.0.X). and is not relevant for an OpenSSL FIPS 140-3 provider, since this is no longer allowed 🚫
  • -self_test_oninstall — the converse of -self_test_onload 🔄 the two fields related to the "test status indicator" and "MAC status indicator" are written to the output configuration file. this field is not relevant for an OpenSSL FIPS 140-3 provider, since this is no longer allowed 🚫
  • -quiet — do not output pass/fail messages 🤐 implies -noout.
  • -corrupt_desc selftest_description, -corrupt_type selftest_type — the corrupt options can be used to test failure of one or more self tests by name 😈 either option or both may be used to select the tests to corrupt. refer to the entries for st-desc and st-type in OSSL_PROVIDER-FIPS(7) for values that can be used.
  • -config parent_config — test that a FIPS provider can be loaded from the specified configuration file. a previous call to this application needs to generate the extra configuration data that is included by the base "parent_config" configuration file 📂 see config(5) for further information on how to set up a provider section. all other options are ignored if -config is used 🚨
  • -defer_tests — configures the module to not run all self-tests at startup and allow tests execution to be deferred to the first time the algorithm to be tested is invoked ⏰ procrastination but make it FIPS-compliant.

📝 NOTES 📝

Self tests results are logged by default if the options -quiet and -noout are not specified, or if either of the options -corrupt_desc or -corrupt_type are used 📋

If the base configuration file is set up to autoload the fips module, then the fips module will be loaded and self tested BEFORE the fipsinstall application has a chance to set up its own self test callback 😭 as a result of this, the self test output and the options -corrupt_desc and -corrupt_type will be ignored. for normal usage the base configuration file should use the default provider when generating the fips configuration file 🙏

lowkey important timeline lore: the -self_test_oninstall option was added and the -self_test_onload option was made the default in OpenSSL 3.1. and the command and all remaining options were added in OpenSSL 3.0 🕰️

✨ EXAMPLES ✨

okay bestie, this is the part where it all comes together 💖 here's literally every scenario you'd ever want, copy-paste ready.

1. Wanna calculate the mac of a FIPS module fips.so AND run a FIPS self test on it, then save your fips.cnf config file? Say less:

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips

2. Now double check that fips.cnf actually holds the right info (vibe check on your own config, iconic):

openssl fipsinstall -module ./fips.so -in fips.cnf  -provider_name fips -verify

3. Feeling chaotic? Corrupt every self test that has the description "SHA1" 🙈:

openssl fipsinstall -module ./fips.so -out fips.cnf -provider_name fips \
        -corrupt_desc 'SHA1'

4. Last one, and it's giving "will my module even load from a base config file" energy. Validate that the fips module can be loaded from a base configuration file:

export OPENSSL_CONF_INCLUDE=<path of configuration files>
export OPENSSL_MODULES=<provider-path>
openssl fipsinstall -config' 'default.cnf'
⚠️ yes the -config' 'default.cnf spacing is weird, we didn't write it, we're just faithfully reporting it fr fr. Character for character, bestie. Don't @ me 💅

👑 SEE ALSO 👑

Go read these when you're done here, they're part of the extended universe:

🌸 HISTORY 🌸

So the lore goes like this: the openssl-fipsinstall application was added in OpenSSL 3.0. Baby's first era 🍼

Then the glow-ups kept coming:

OpenSSL 3.1 brought us:

  • -ems_check
  • -self_test_oninstall

OpenSSL 3.2 added:

  • -pedantic
  • -no_drbg_truncated_digests

OpenSSL 3.4 was a whole era, adding:

  • -hmac_key_check
  • -kmac_key_check
  • -signature_digest_check
  • -hkdf_digest_check
  • -tls13_kdf_digest_check
  • -tls1_prf_digest_check
  • -sshkdf_digest_check
  • -sskdf_digest_check
  • -x963kdf_digest_check
  • -dsa_sign_disabled
  • -no_pbkdf2_lower_bound_check
  • -no_short_mac
  • -tdes_encrypt_disabled
  • -rsa_pkcs15_padding_disabled
  • -rsa_pss_saltlen_check
  • -rsa_sign_x931_disabled
  • -hkdf_key_check
  • -kbkdf_key_check
  • -tls13_kdf_key_check
  • -tls1_prf_key_check
  • -sshkdf_key_check
  • -sskdf_key_check
  • -x963kdf_key_check
  • -x942kdf_key_check
  • -ecdh_cofactor_check

OpenSSL 4.0 added one single queen:

  • -defer_tests

Copyright 2019-2026 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

and that's the whole page bestie, you made it to the end 🎀 this one was OPENSSL-FIPSINSTALL(1SSL), version 4.0.3, dated 2026-09-29 — go forth and fipsinstall responsibly, ily, no cap ✨💅🦋

📦 where this page comes from