OSSL_PROVIDER-FIPS(7SSL)

📦
version 4.0.3 · 13 versions
, in ubuntu stonking

💅 OSSL_PROVIDER-FIPS 💅

okay bestie, welcome to the OSSL_PROVIDER-FIPS page — that's section 7SSL of the OpenSSL manual, and it's literally about the certified glow-up module of OpenSSL. this is part 1, so don't go anywhere. 💖

✨ NAME ✨

OSSL_PROVIDER-FIPS — the OpenSSL FIPS provider. periodt.

🦋 DESCRIPTION 🦋

so the OpenSSL FIPS provider is a special provider that conforms to the Federal Information Processing Standards (FIPS) laid out in FIPS 140-3. this module ships an approved set of cryptographic algorithms that some accredited testing laboratory has actually validated. no cap. 👑

🌸 Properties 🌸

the implementations in this provider have these properties set, specifically for the approved algorithms:

  • "provider=fips"
  • "fips=yes"

you can drop these into a property query string with fetching functions like EVP_MD_fetch(3) or EVP_CIPHER_fetch(3), and also with any other function that takes a property query string, like EVP_PKEY_CTX_new_from_name(3).

to be FIPS compliant, it is mandatory to include "fips=yes" as part of all property queries. that's what guarantees only FIPS approved implementations get used for cryptographic operations. and lowkey the "fips=yes" query may also pull in other non-crypto support operations that aren't even in the FIPS provider — like asymmetric key encoders, see "Asymmetric Key Management" in OSSL_PROVIDER-default(7).

it is not mandatory to include "provider=fips" in your property query. but including "provider=fips" guarantees that the OpenSSL FIPS provider is used for cryptographic operations rather than some other FIPS capable provider. it's giving "be specific, girl". 💅

🎀 Approved algorithms 🎀

algorithms fetched with "fips=yes" may still be unapproved if certain conditions aren't met. see "FIPS indicators" in fips_module(7) for the extra info. every "fips=yes" algorithm implementation supplied by this provider exposes a gettable "fips-indicator" context parameter and returns 1 when the operation is approved. 🫶

⚠️ applications must not treat a missing indicator as an assertion of FIPS approval. that's a big no no. 🙈

💜 Provider parameters 💜

see "Provider parameters" in provider-base(7) for a list of base parameters. the OpenSSL FIPS provider also handles FIPS indicator related parameters, exactly as specified by "FIPS indicator options" in fips_config(5).

🌈 OPERATIONS AND ALGORITHMS 🌈

the OpenSSL FIPS provider supports these operations and algorithms:

⭐ Hashing Algorithms / Message Digests ⭐

🍓 Symmetric Ciphers 🍓

🧚 Message Authentication Code (MAC) 🧚

💖 Key Derivation Function (KDF) 💖

🦋 Key Exchange 🦋

👑 Asymmetric Signature 👑

🌸 Asymmetric Cipher 🌸

⭐ Asymmetric Key Encapsulation ⭐

💜 Asymmetric Key Management 💜

🎀 Random Number Generation 🎀

🔥 STATUS INDICATOR 🔥

FIPS 140-3 requires that services provide an indicator when the service uses an approved cryptographic algorithm in an approved manner. in most cases the status can be determined implicitly by just observing the return code from an approved security service call — but the FIPS provider module may permit the use of approved cryptographic algorithms in a non-approved manner in some cases. 👀

for this, the Ubuntu FIPS provider module provides an explicit status indicator, implemented as a gettable provider module parameter, and you can access it using OSSL_PROVIDER_get_params(3) on the OSSL_PROVIDER associated with the FIPS provider module.

see OSSL_PARAM(3) for info about passing parameters.

the following OSSL_PARAM key is used for accessing the status indicator:

  • "ubuntu.fips-unapproved-usage"
    • (UBUNTU_OSSL_PROV_FIPS_PARAM_UNAPPROVED_USAGE) <integer> — gets 1 if the OSSL_LIB_CTX(3) associated with the OSSL_PROVIDER has been used to execute a security service call that used an approved cryptographic algorithm in a non-approved manner inside the FIPS provider module. querying this parameter resets it to 0. note that this only applies to services inside of the FIPS provider module boundary — it cannot indicate whether the OSSL_LIB_CTX has been used to execute security service calls in other provider modules. 🙈

okay that's the lore so far... 👀 more parts coming, don't touch that dial 💖

🧪 SELF TESTING 🧪

Okay bestie, so here's the thing about FIPS modules — they're required to run cryptographic algorithm self tests. That's just the vibe. FIPS 140-3 says you need known answer tests running on startup, plus conditional tests that run while cryptographic operations are happening. Both. Always. No skipping. 💅

There's an optional callback mechanism you can use to get info back out to the user — that's what OSSL_SELF_TEST_set_callback(3) is for. 🫶

The parameters passed to that callback are described over in OSSL_SELF_TEST_new(3).

The OpenSSL FIPS module uses the mechanism below to spill all the tea about the self tests as they run. Super useful for debugging if a self test is failing. The callback also lets you force any self test to fail, so you can check that it behaves correctly when things go wrong. And heads up: all self tests run even if a self test failure occurs. It doesn't just stop and cry, it keeps going. 😭

The types the FIPS module passes to OSSL_SELF_TEST_onbegin()

  • "Module_Integrity" (OSSL_SELF_TEST_TYPE_MODULE_INTEGRITY) — uses HMAC SHA256 on the module file to validate that the module has not been modified. The integrity value gets compared to a value written to a configuration file during installation. 🔒
  • "KAT_Mac" (OSSL_SELF_TEST_TYPE_KAT_MAC) — used during the Module Integrity test to perform a known answer test on HMAC SHA256 before using it. In pre-4.0 versions, OSSL_SELF_TEST_TYPE_KAT_INTEGRITY ("KAT_Integrity") was used for this instead.
  • "KAT_Cipher" (OSSL_SELF_TEST_TYPE_KAT_CIPHER) — known answer test for a symmetric cipher.
  • "KAT_AsymmetricCipher" (OSSL_SELF_TEST_TYPE_KAT_ASYM_CIPHER) — known answer test for a asymmetric cipher.
  • "KAT_Digest" (OSSL_SELF_TEST_TYPE_KAT_DIGEST) — known answer test for a digest.
  • "KAT_AsymmetricKeyGeneration" (OSSL_SELF_TEST_TYPE_KAT_ASYM_KEYGEN) — known answer test for asymmetric key generation.
  • "KAT_Signature" (OSSL_SELF_TEST_TYPE_KAT_SIGNATURE) — known answer test for a signature.
  • "PCT_Signature" (OSSL_SELF_TEST_TYPE_PCT_SIGNATURE) — pairwise consistency check for a signature.
  • "KAT_KDF" (OSSL_SELF_TEST_TYPE_KAT_KDF) — known answer test for a key derivation function.
  • "KAT_KA" (OSSL_SELF_TEST_TYPE_KAT_KA) — known answer test for key agreement.
  • "KAT_KEM" (OSSL_SELF_TEST_TYPE_KAT_KEM) — known answer test for key encapsulation.
  • "DRBG" (OSSL_SELF_TEST_TYPE_DRBG) — known answer test for a deterministic random bit generator.
  • "Conditional_PCT" (OSSL_SELF_TEST_TYPE_PCT) — conditional test that is run during the generation of key pairs.
  • "Import_PCT" (OSSL_SELF_TEST_TYPE_PCT_IMPORT) — conditional test that is run during the import of key pairs.
  • "Conditional_KAT" (OSSL_SELF_TEST_TYPE_PCT_KAT) — conditional test run during generation that derive the public key from the private key and checks that the public key matches. This is a SP 800-56A requirement, btw.
  • "Continuous_RNG_Test" (OSSL_SELF_TEST_TYPE_CRNG) — continuous random number generator test.
  • "Install_Integrity" (OSSL_SELF_TEST_TYPE_INSTALL_INTEGRITY) — this is deprecated. The option is no longer used since FIPS 140-3 requires self tests to always run on startup. Previous FIPS 140-2 validations allowed the self tests to be run just once. Rip old behavior, you will not be missed 🪦

The descriptions the FIPS module passes to OSSL_SELF_TEST_onbegin()

  • "HMAC" (OSSL_SELF_TEST_DESC_INTEGRITY_HMAC) — "Module_Integrity" uses this one.
  • "RSA" (OSSL_SELF_TEST_DESC_PCT_RSA_PKCS1)
  • "RSA" (OSSL_SELF_TEST_DESC_PCT_RSA)
  • "ECDSA" (OSSL_SELF_TEST_DESC_PCT_ECDSA)
  • "EDDSA" (OSSL_SELF_TEST_DESC_PCT_EDDSA)
  • "DSA" (OSSL_SELF_TEST_DESC_PCT_DSA)
  • "ML-DSA" (OSSL_SELF_TEST_DESC_PCT_ML_DSA)
  • "ML-KEM" (OSSL_SELF_TEST_DESC_PCT_ML_KEM)
  • "SLH-DSA" (OSSL_SELF_TEST_DESC_PCT_SLH_DSA)

Key generation tests used with the "Pairwise_Consistency_Test" type.

  • "RSA_Encrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_ENC)
  • "RSA_Decrypt" (OSSL_SELF_TEST_DESC_ASYM_RSA_DEC)

"KAT_AsymmetricCipher" uses this to indicate an encrypt or decrypt KAT.

  • "ML-DSA" (OSSL_SELF_TEST_DESC_KEYGEN_ML_DSA)
  • "ML-KEM" (OSSL_SELF_TEST_DESC_KEYGEN_ML_KEM)
  • "SLH-DSA" (OSSL_SELF_TEST_DESC_KEYGEN_SLH_DSA)

"KAT_AsymmetricKeyGeneration" uses this to indicate a key generation KAT.

  • "AES_GCM" (OSSL_SELF_TEST_DESC_CIPHER_AES_GCM)
  • "AES_ECB_Decrypt" (OSSL_SELF_TEST_DESC_CIPHER_AES_ECB)
  • "TDES" (OSSL_SELF_TEST_DESC_CIPHER_TDES)

Symmetric cipher tests used with the "KAT_Cipher" type.

  • "SHA1" (OSSL_SELF_TEST_DESC_MD_SHA1)
  • "SHA2" (OSSL_SELF_TEST_DESC_MD_SHA2)
  • "SHA3" (OSSL_SELF_TEST_DESC_MD_SHA3)

Digest tests used with the "KAT_Digest" type.

  • "DSA" (OSSL_SELF_TEST_DESC_SIGN_DSA)
  • "RSA" (OSSL_SELF_TEST_DESC_SIGN_RSA)
  • "ECDSA" (OSSL_SELF_TEST_DESC_SIGN_ECDSA)
  • "DetECDSA" (OSSL_SELF_TEST_DESC_SIGN_DetECDSA)
  • "EDDSA" (OSSL_SELF_TEST_DESC_SIGN_EDDSA)
  • "LMS" (OSSL_SELF_TEST_DESC_SIGN_LMS)
  • "ML-DSA" (OSSL_SELF_TEST_DESC_SIGN_ML_DSA)
  • "SLH-DSA" (OSSL_SELF_TEST_DESC_SIGN_SLH_DSA)

Signature tests used with the "KAT_Signature" type.

  • "ECDH" (OSSL_SELF_TEST_DESC_KA_ECDH)
  • "DH" (OSSL_SELF_TEST_DESC_KA_DH)

Key agreement tests used with the "KAT_KA" type.

  • "HKDF" (OSSL_SELF_TEST_DESC_KDF_HKDF)
  • "TLS13_KDF_EXTRACT" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXTRACT)
  • "TLS13_KDF_EXPAND" (OSSL_SELF_TEST_DESC_KDF_TLS13_EXPAND)
  • "SSKDF" (OSSL_SELF_TEST_DESC_KDF_SSKDF)
  • "X963KDF" (OSSL_SELF_TEST_DESC_KDF_X963KDF)
  • "X942KDF" (OSSL_SELF_TEST_DESC_KDF_X942KDF)
  • "PBKDF2" (OSSL_SELF_TEST_DESC_KDF_PBKDF2)
  • "SNMPKDF" (OSSL_SELF_TEST_DESC_KDF_SNMPKDF)
  • "SRTPKDF" (OSSL_SELF_TEST_DESC_KDF_SRTPKDF)
  • "SSHKDF" (OSSL_SELF_TEST_DESC_KDF_SSHKDF)
  • "TLS12_PRF" (OSSL_SELF_TEST_DESC_KDF_TLS12_PRF)
  • "KBKDF" (OSSL_SELF_TEST_DESC_KDF_KBKDF)

Key Encapsulation Function tests used with the "KAT_KEM" type.

  • "KEM_Encap" (OSSL_SELF_TEST_DESC_ENCAP_KEM)
  • "KEM_Decap" (OSSL_SELF_TEST_DESC_DECAP_KEM)
  • "KEM_Decap_Reject" (OSSL_SELF_TEST_DESC_DECAP_REJ_KEM)

Key Derivation Function tests used with the "KAT_KDF" type.

  • "CTR" (OSSL_SELF_TEST_DESC_DRBG_CTR)
  • "HASH" (OSSL_SELF_TEST_DESC_DRBG_HASH)
  • "HMAC" (OSSL_SELF_TEST_DESC_DRBG_HMAC)

DRBG tests used with the "DRBG" type.

  • "RNG" (OSSL_SELF_TEST_DESC_RNG)

"Continuous_RNG_Test" uses this.

✨ EXAMPLES ✨

Here's a cute lil self test callback, shown below for illustrative purposes. It's giving "hello world but make it FIPS." 👑

#include <openssl/self_test.h>

static OSSL_CALLBACK self_test_cb;

static int self_test_cb(const OSSL_PARAM params[], void *arg)
{
  int ret = 0;
  const OSSL_PARAM *p = NULL;
  const char *phase = NULL, *type = NULL, *desc = NULL;

  p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_PHASE);
  if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
      goto err;
  phase = (const char *)p->data;

  p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_DESC);
  if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
      goto err;
  desc = (const char *)p->data;

  p = OSSL_PARAM_locate_const(params, OSSL_PROV_PARAM_SELF_TEST_TYPE);
  if (p == NULL || p->data_type != OSSL_PARAM_UTF8_STRING)
      goto err;
  type = (const char *)p->data;

  /* Do some logging */
  if (strcmp(phase, OSSL_SELF_TEST_PHASE_START) == 0)
      BIO_printf(bio_out, "%s : (%s) : ", desc, type);
  if (strcmp(phase, OSSL_SELF_TEST_PHASE_PASS) == 0
          || strcmp(phase, OSSL_SELF_TEST_PHASE_FAIL) == 0)
      BIO_printf(bio_out, "%s\n", phase);

  /* Corrupt the SHA1 self test during the 'corrupt' phase by returning 0 */
  if (strcmp(phase, OSSL_SELF_TEST_PHASE_CORRUPT) == 0
          && strcmp(desc, OSSL_SELF_TEST_DESC_MD_SHA1) == 0) {
      BIO_printf(bio_out, "%s %s", phase, desc);
      return 0;
  }
  ret = 1;
err:
  return ret;
}

📝 NOTES 📝

Okay so, some released versions of OpenSSL do not include a validated FIPS provider. To figure out which versions actually went through the validation process, go check the OpenSSL Downloads page <https://www.openssl.org/source/>. If you need FIPS-approved functionality, it is essential to build your FIPS provider using one of the validated versions listed there. Don't freestyle it bestie, this is the whole point. 🙈

But here's the slay part — normally you can use a FIPS provider built from one of those validated versions alongside libcrypto and libssl compiled from any release within the same major release series. That flexibility is how you get bug fixes and CVEs patched when they fall outside the FIPS boundary. 🎀

You can load the FIPS provider into multiple library contexts like any other provider. However, the following restriction applies: the FIPS provider cannot be used by multiple copies of OpenSSL libcrypto in a single process.

Here's why, and it's lowkey cursed: the provider saves core callbacks to the libcrypto it got in the OSSL_provider_init() call into global data. So if subsequent invocations of its OSSL_provider_init() function hand it different addresses for those callbacks than the initial call did, it will fail. 💀

When does that happen? When different copies of libcrypto are hanging out in the process memory and both try to load the same FIPS provider. Awkward. 😬

A workaround: load a different copy of the FIPS provider for each of the libcrypto instances in the process. Iconic problem-solving, honestly. 🌈

👀 SEE ALSO 👀

openssl-fipsinstall(1), fips_config(5), OSSL_SELF_TEST_set_callback(3), OSSL_SELF_TEST_new(3), OSSL_PARAM(3), openssl-core.h(7), openssl-core_dispatch.h(7), provider(7), <https://www.openssl.org/source/>

🕰️ HISTORY 🕰️

  • The HKDF-SHA256, HKDF-SHA384 and HKDF-SHA512 algorithms were added in OpenSSL 3.6. ✨
  • The CSHAKE-128 and CSHAKE-256 algorithms were added in OpenSSL 4.0. 🦋
  • All other functionality was added in OpenSSL 3.0. The origin story, fr fr.

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 a wrap on part 2, bestie!! 🫶 This whole thing came from OpenSSL 4.0.3, dated 2026-09-29, and it's filed under OSSL_PROVIDER-FIPS(7SSL). Go forth and self-test responsibly. 💖✨🎀

📦 where this page comes from