fips_module_indicators.7ossl - Man Page

The Red Hat OpenSSL FIPS provider exports a symbol named redhat_ossl_query_fipsindicator that provides information 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).

    #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_RH_FIPSINDICATOR_ALORITHM *(*redhat_ossl_query_fipsindicator)(int) \
        = dlsym(provider, "redhat_ossl_query_fipsindicator");
    if (redhat_ossl_query_fipsindicator == NULL) {
        fprintf(stderr, "%s\n", dlerror());
        fprintf(stderr, "Does your copy of fips.so have the required Red Hat"
                        " patches?\n");
        // handle error
    }

Note that this uses the providers/fips/indicator.h header, which is not public. Install the openssl-debugsource package from the BaseOS-debuginfo repository using dnf debuginfo-install openssl and include /usr/src/debug/openssl-3.*/ in the compiler's include path.

redhat_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_RH_FIPSINDICATOR_STRUCTs. On failure, NULL is returned. The last entry in the array is indicated by algorithm_names being NULL.

    typedef struct ossl_rh_fipsindicator_algorithm_st {
        const char *algorithm_names;     /* key */
        const char *property_definition; /* key */
        const OSSL_RH_FIPSINDICATOR_DISPATCH *indicators;
    } OSSL_RH_FIPSINDICATOR_ALGORITHM;

    typedef struct ossl_rh_fipsindicator_dispatch_st {
        int function_id;
        int approved;
    } OSSL_RH_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_RH_FIPSINDICATOR_DISPATCH *indicator_dispatch = NULL;
    const OSSL_RH_FIPSINDICATOR_ALGORITHM *indicator =
        redhat_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_RH_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. approved is OSSL_RH_FIPSINDICATOR_APPROVED if the operation is an approved security service, or part of an approved security service, or OSSL_RH_FIPSINDICATOR_UNAPPROVED otherwise. Any other value is invalid. 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_RH_FIPSINDICATOR_APPROVED:
                    // approved security service
                    break;
                case OSSL_RH_FIPSINDICATOR_UNAPPROVED:
                    // unapproved security service
                    break;
                default:
                    // invalid result
                    break;
            }
            break;
        }
    }