CONF_MODULES_LOAD_FILE(3ossl)

📦

version 15.1 · 2 versions

15.1 · freebsd 15.1 (latest)
14.5 · freebsd 14.5

💅 CONF_MODULES_LOAD_FILE(3ossl) — the OpenSSL config-loading glow-up

ok so bestie, this is page CONF_MODULES_LOAD_FILE(3ossl) from the OpenSSL manual, and it's literally all about the OpenSSL configuration functions. six-ish functions, one big vibe, and yes we're gonna go through every single flag because that's just who we are. 🎀

✨ NAME ✨

CONF_get1_default_config_file, CONF_modules_load_file_ex, CONF_modules_load_file, CONF_modules_load — OpenSSL configuration functions. that's the whole squad rn. 👑

🌸 SYNOPSIS 🌸

#include <openssl/conf.h>

char *CONF_get1_default_config_file(void);
int CONF_modules_load_file_ex(OSSL_LIB_CTX *libctx, const char *filename,
                              const char *appname, unsigned long flags);
int CONF_modules_load_file(const char *filename, const char *appname,
                           unsigned long flags);
int CONF_modules_load(const CONF *cnf, const char *appname,
                      unsigned long flags);

look at them, all lined up and iconic. 🫶

🦋 DESCRIPTION 🦋

`CONF_get1_default_config_file()`

this one figures out the default configuration file pathname for you, and honestly the way it decides is giving main character energy. here's the tea:

if the OPENSSL_CONF environment variable is set, its value is what gets returned. periodt.
otherwise, the function returns the path you get using X509_get_default_cert_area(3) with the filename "openssl.cnf" appended to it.

and heads up bestie, the caller is responsible for freeing any string returned. that memory is yours now, no takebacks. 🙈

`CONF_modules_load_file_ex()`

this is the one that configures OpenSSL, using:

library context libctx
file filename
application name appname

and the deets:

if filename is NULL, the standard OpenSSL configuration file is used, as determined by calling CONF_get1_default_config_file().
if appname is NULL, the standard OpenSSL application name openssl_conf is used.
the behaviour can be customized using flags.

ngl there's a little plot twist: the error suppressing can be overridden by config_diagnostics as described in config(5). iykyk. 😭

`CONF_modules_load_file()`

lowkey the same as CONF_modules_load_file_ex() but has a NULL library context. that's it, that's the difference. 💀

`CONF_modules_load()`

identical to CONF_modules_load_file() except it reads configuration information from cnf. it's the "i brought my own config" option and we respect it. 💜

🎀 NOTES 🎀

the following flags are currently recognized, and yes we're doing all of them, buckle up:

CONF_MFLAGS_IGNORE_ERRORS — if set, errors returned by individual configuration modules are ignored. if not set, the first module error is considered fatal and no further modules are loaded. dramatic? yes. accurate? also yes. 🔥
CONF_MFLAGS_SILENT — normally any modules errors will add error information to the error queue. if this is set, no error information is added. quiet luxury. 🤫
CONF_MFLAGS_IGNORE_RETURN_CODES — if set, the function unconditionally returns success. this is used by default in OPENSSL_init_crypto(3) to ignore any errors in the default system-wide configuration file, because having all OpenSSL applications fail to start when there are potentially minor issues in the file is too risky. applications calling CONF_modules_load_file_ex explicitly should not generally set this flag. ma'am, read that again. 📢
CONF_MFLAGS_NO_DSO — if set, configuration module loading from DSOs is disabled. no DSOs, no problem. 🚫
CONF_MFLAGS_IGNORE_MISSING_FILE — if set, will make CONF_load_modules_file() ignore missing configuration files. normally a missing configuration file return an error. (copied that exactly, don't come for me 💅)
CONF_MFLAGS_DEFAULT_SECTION — if set and appname is not NULL, will use the default section pointed to by openssl_conf if appname does not exist. fallback queen behavior. 👑

by using CONF_modules_load_file_ex() with appropriate flags, an application can customise application configuration to best suit its needs. in some cases the use of a configuration file is optional and its absence is not an error: in this case CONF_MFLAGS_IGNORE_MISSING_FILE would be set. ✨

errors during configuration may also be handled differently by different applications. for example, in some cases an error may simply print out a warning message and the application continue. in other cases, an application might consider a configuration file error as fatal and exit immediately. different strokes for different apps, fr fr.

applications can use the CONF_modules_load() function if they wish to load a configuration file themselves and have finer control over how errors are treated. independent icon things. 🌈

⭐ RETURN VALUES ⭐

these functions return 1 for success and a zero or negative value for failure.

if module errors are not ignored, the return code will reflect the return value of the failing module — and that will always be zero or negative. so like, not a success, in case that wasn't clear. 💀

🔥 EXAMPLES 🔥

load a config file, print out any errors, and exit (missing file = fatal)

if (CONF_modules_load_file_ex(libctx, NULL, NULL, 0) <= 0) {
    fprintf(stderr, "FATAL: error loading configuration file\n");
    ERR_print_errors_fp(stderr);
    exit(1);
}

load the default config file using the section indicated by `"myapp"`, tolerate missing files, but exit on other errors

if (CONF_modules_load_file_ex(NULL, NULL, "myapp",
                              CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
    fprintf(stderr, "FATAL: error loading configuration file\n");
    ERR_print_errors_fp(stderr);
    exit(1);
}

load a custom config file and section, only print warnings on error, missing config file ignored

if (CONF_modules_load_file_ex(NULL, "/something/app.cnf", "myapp",
                              CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
    fprintf(stderr, "WARNING: error loading configuration file\n");
    ERR_print_errors_fp(stderr);
}

load and parse the config file manually, custom error handling

FILE *fp;
CONF *cnf = NULL;
long eline;

fp = fopen("/somepath/app.cnf", "r");
if (fp == NULL) {
    fprintf(stderr, "Error opening configuration file\n");
    /* Other missing configuration file behaviour */
} else {
    cnf = NCONF_new_ex(libctx, NULL);
    if (NCONF_load_fp(cnf, fp, &eline) == 0) {
        fprintf(stderr, "Error on line %ld of configuration file\n", eline);
        ERR_print_errors_fp(stderr);
        /* Other malformed configuration file behaviour */
    } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
        fprintf(stderr, "Error configuring application\n");
        ERR_print_errors_fp(stderr);
        /* Other configuration error behaviour */
    }
    fclose(fp);
    NCONF_free(cnf);
}

four whole examples, all of them serving. go off. 🍓

the whole friend group, love them for you. 🫶

👑 COPYRIGHT 👑

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>.

okay that's the whole page, no skips no crumbs. this was OpenSSL 3.5.6, dated 2026-04-07, and the manual page is CONF_MODULES_LOAD_FILE(3ossl) — go forth and configure your little heart out bestie, ily, bye! 💖🦋✨

📦 where this page comes from

freebsd 15.1: base 15.1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms