CONF_MODULES_LOAD_FILE(3)

💅 CONF_MODULES_LOAD_FILE(3) — the OpenSSL config glow-up page 🎀

okay so bestie, this is page CONF_MODULES_LOAD_FILE(3) from the Library Functions Manual, and it's literally all about the OpenSSL configuration functions: CONF_modules_load_file, CONF_modules_load, and X509_get_default_cert_area. sit down, hydrate, and let's get into it ✨

---

🌸 NAME 🌸

CONF_modules_load_file, CONF_modules_load, X509_get_default_cert_area — the OpenSSL configuration functions, aka the girlies that actually read your config 🫶

---

✨ SYNOPSIS ✨

#include <openssl/conf.h>

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);

#include <openssl/x509.h>

const char *
X509_get_default_cert_area(void);

---

💖 DESCRIPTION 💖

CONF_modules_load_file() sets up OpenSSL for you using the file filename — which has to be in openssl.cnf(5) format — plus the application name appname. 💅

So here's the tea on defaults, iykyk:

• if filename is NULL, it uses the standard OpenSSL config file /etc/ssl/openssl.cnf
• if appname is NULL, it uses the standard OpenSSL application name "openssl_conf"
• and you can customize the behaviour with flags, obviously 👑

fr fr, check the “EXAMPLES” section (down below, bestie, keep scrolling) for the extra functions you might need to call. calling config functions in the right order to get what you actually want is lowkey tricky, because so many config functions internally call each other — it's giving tangled earphones 😭

CONF_modules_load() is literally identical to CONF_modules_load_file() except it reads the config info from cnf instead. same energy, different source 💜

these are the flags that are currently recognized:

• CONF_MFLAGS_IGNORE_ERRORS — ignore the errors that individual configuration modules return. by default, the first module error is considered fatal and no further modules get loaded. 💀
• CONF_MFLAGS_SILENT — don't add any error information. by default, all module errors add error information to the error queue.
• CONF_MFLAGS_NO_DSO — disables loading of configuration modules from DSOs. this flag only exists for compatibility and has no effect, so it's giving decorative 🎀
• CONF_MFLAGS_IGNORE_MISSING_FILE — lets CONF_modules_load_file() ignore missing configuration files. by default, a missing config file returns an error. 🙈
• CONF_MFLAGS_DEFAULT_SECTION — if appname is not NULL but doesn't exist, it falls back to the default section "openssl_conf". slay, backup plan ✨

by using CONF_modules_load_file() with the right flags, an app can customize its application configuration to best suit its needs. in some cases the config file is optional and its absence isn't an error at all — in that case you'd set CONF_MFLAGS_IGNORE_MISSING_FILE. easy 💅

errors during configuration can also be handled differently by different applications. for example, in some cases an error may simply print out a warning message and the app just continues. in other cases an app might treat a config file error as fatal and exit immediately. both are valid, no judgement 🫶

applications can use CONF_modules_load() if they want to load a config file themselves and have finer control over how errors are treated. main character energy: doing it yourself 👑

---

🔥 RETURN VALUES 🔥

CONF_modules_load_file() and CONF_modules_load() return 1 for success, and zero or a 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, no cap).

X509_get_default_cert_area() returns a pointer to the constant string "/etc/ssl". that's it, that's the whole function 🎀

---

🦋 FILES 🦋

• /etc/ssl — standard configuration directory
• /etc/ssl/openssl.cnf — standard configuration file

---

🌈 EXAMPLES 🌈

Load a configuration file and print out any errors and exit (missing file is considered fatal):

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

Load the default configuration file using the section indicated by "myapp", tolerate missing files, but exit on other errors:

if (CONF_modules_load_file(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 configuration file and section instead of the standard one, only print warnings on error, missing configuration file ignored:

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

okay so about that last example 👆 the call to OPENSSL_no_config(3) is required first to suppress automatic loading of the standard configuration file, and the call to OPENSSL_load_builtin_modules(3) is needed so the configuration of builtin modules gets loaded in addition to the configuration of "myapp". don't skip these, bestie, they're the whole vibe check ⭐

Load and parse the configuration file manually, with 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(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);
}

---

💜 SEE ALSO 💜

CONF_modules_free(3), ERR(3), OPENSSL_config(3), OPENSSL_load_builtin_modules(3) — go read those too, bestie, they're all connected 🧚

---

👑 HISTORY 👑

X509_get_default_cert_area() first appeared in SSLeay 0.4.1 and has been available since OpenBSD 2.4. vintage 💅

CONF_modules_load_file() and CONF_modules_load() first appeared in OpenSSL 0.9.7 and have been available since OpenBSD 3.2. icons only ✨

---

and that's the page, bestie!! 🍓 this cutie came from Debian, dated November 19, 2023, and the source/version line was CONF_MODULES_LOAD_FILE(3) — now go configure something iconic 💖🎀🦋