FIPS_MODULE_INDICATORS(7ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💖 FIPS_MODULE_INDICATORS 💖

okay so this is FIPS_MODULE_INDICATORS(7ossl) — it lives in the OpenSSL corner of the manual, and it's genuinely the most niche little guide, but we're getting into it together 🫶

🌸 NAME 🌸

fips_module_indicators — the SUSE OpenSSL FIPS module indicators guide. that's it, that's the name, it ate ✨

✨ DESCRIPTION ✨

Bestie, gather round. This guide documents how the SUSE Linux Enterprise OpenSSL FIPS provider implements Approved Security Service Indicators according to the FIPS 140-3 Implementation Guidelines, section 2.4.C. if you want to go straight to the source, the guidelines live at:

<https://csrc.nist.gov/CSRC/media/Projects/cryptographic-module-validation-program/documents/fips%20140-3/FIPS%20140-3%20IG.pdf>

and that's for the FIPS 140-3 Implementation Guidelines, no cap.

So here's the tea ☕ — for all approved services except signatures, the SUSE OpenSSL FIPS provider just uses the return code as the indicator, as understood by FIPS 140-3. which lowkey means:

  • every operation that succeeds denotes use of an approved security service ✅
  • operations that do not succeed may not have been approved security services, or may have been used incorrectly 👀

For signatures though, it's giving main character energy — there's an explicit indicator API available to determine whether a selected operation is an approved security service, and you use it in combination with the return code of the operation. For a signature operation to be approved: the explicit indicator must claim it as approved, and it must succeed. both. periodt.

🎀 Querying the explicit indicator 🎀

The SUSE OpenSSL FIPS provider exports a symbol named suse_ossl_query_fipsindicator that hands you the info on which signature operations are approved security functions. To use this function, either link against fips.so directly, or load it at runtime using dlopen(3) and dlsym(3). slay 🔥

#include <openssl/core_dispatch.h>
#include "providers/fips/indicator.h"

void *provider = dlopen("/usr/lib64/ossl-modules/fips.so", RTLD_LAZY);
if (provider == NULL) {
    fprintf(stderr, "%s\n", dlerror());
    // handle error
}

const OSSL_SUSE_FIPSINDICATOR_ALGORITHM *(*suse_ossl_query_fipsindicator)(int) \
    = dlsym(provider, "suse_ossl_query_fipsindicator");
if (suse_ossl_query_fipsindicator == NULL) {
    fprintf(stderr, "%s\n", dlerror());
    fprintf(stderr, "Does your copy of fips.so have the required SUSE"
                    " patches?\n");
    // handle error
}
⚠️ ngl, heads up: this uses the providers/fips/indicator.h header, which is not public. To get it, install the openssl-3-debugsource package from the Debuginfo-Pool repository using zypper install openssl-3-debugsource and include /usr/src/debug/openssl-3.*/ in the compiler's include path. iconic but slightly chaotic 💅

suse_ossl_query_fipsindicator expects an operation ID as its only argument. Currently, the only supported operation ID is OSSL_OP_SIGNATURE to obtain the indicators for signature operations. On success, the return value is a pointer to an array of OSSL_SUSE_FIPSINDICATOR_STRUCTs. On failure, NULL is returned. The last entry in the array is indicated by algorithm_names being NULL. 🦋

typedef struct ossl_suse_fipsindicator_algorithm_st {
    const char *algorithm_names;     /* key */
    const char *property_definition; /* key */
    const OSSL_SUSE_FIPSINDICATOR_DISPATCH *indicators;
} OSSL_SUSE_FIPSINDICATOR_ALGORITHM;

typedef struct ossl_suse_fipsindicator_dispatch_st {
    int function_id;
    int approved;
} OSSL_SUSE_FIPSINDICATOR_DISPATCH;

The algorithm_names field is a colon-separated list of algorithm names from one of the PROV_NAMES_... constants, e.g., PROV_NAMES_RSA. strtok(3) can be used to locate the appropriate entry. See the example below, where algorithm contains the algorithm name to search for: 🔍

const OSSL_SUSE_FIPSINDICATOR_DISPATCH *indicator_dispatch = NULL;
const OSSL_SUSE_FIPSINDICATOR_ALGORITHM *indicator =
    suse_ossl_query_fipsindicator(operation_id);
if (indicator == NULL) {
    fprintf(stderr, "No indicator for operation, probably using implicit"
                    " indicators.\n");
    // handle error
}

for (; indicator->algorithm_names != NULL; ++indicator) {
    char *algorithm_names = strdup(indicator->algorithm_names);
    if (algorithm_names == NULL) {
        perror("strdup(3)");
        // handle error
    }

    const char *algorithm_name = strtok(algorithm_names, ":");
    for (; algorithm_name != NULL; algorithm_name = strtok(NULL, ":")) {
        if (strcasecmp(algorithm_name, algorithm) == 0) {
            indicator_dispatch = indicator->indicators;
            free(algorithm_names);
            algorithm_names = NULL;
            break;
        }
    }
    free(algorithm_names);
}
if (indicator_dispatch == NULL) {
    fprintf(stderr, "No indicator for algorithm %s.\n", algorithm);
    // handle error
}

If an appropriate OSSL_SUSE_FIPSINDICATOR_DISPATCH array is available for the given algorithm name, it maps function IDs to their approval status. The last entry is indicated by a zero function_id. And approved is either:

  • OSSL_SUSE_FIPSINDICATOR_APPROVED if the operation is an approved security service, or part of an approved security service 👑
  • OSSL_SUSE_FIPSINDICATOR_UNAPPROVED otherwise 🙈

Any other value is invalid. no in-between, bestie. Function IDs are OSSL_FUNC_* constants from openssl/core_dispatch.h, e.g., OSSL_FUNC_SIGNATURE_DIGEST_SIGN_UPDATE or OSSL_FUNC_SIGNATURE_SIGN.

Assuming function_id is the function in question, the following code can be used to query the approval status: 💜

for (; indicator_dispatch->function_id != 0; ++indicator_dispatch) {
    if (indicator_dispatch->function_id == function_id) {
        switch (indicator_dispatch->approved) {
            case OSSL_SUSE_FIPSINDICATOR_APPROVED:
                // approved security service
                break;
            case OSSL_SUSE_FIPSINDICATOR_UNAPPROVED:
                // unapproved security service
                break;
            default:
                // invalid result
                break;
        }
        break;
    }
}

🌈 SEE ALSO 🌈

go read those too, iykyk 📚

Copyright 2022 Red Hat, Inc. All Rights Reserved. Copyright 2024 SUSE LLC. 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 vibe check, bestie 🧚 this little gem is from OpenSSL 3.5.0, dated 2026-09-25, and it's filed under FIPS_MODULE_INDICATORS(7ossl). go forth and query those indicators, you absolute icon ⭐💖

📦 where this page comes from