CONF_MODULES_LOAD_FILE(3)

NAME
CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions

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

DESCRIPTION
The function CONF_modules_load_file() configures OpenSSL using the file filename in openssl.cnf(5) format and the application name appname. If filename is NULL, the standard OpenSSL configuration file /etc/ssl/openssl.cnf is used. If appname is NULL, the standard OpenSSL application name "openssl_conf" is used. The behaviour can be customized using flags.

CONF_modules_load() is identical to CONF_modules_load_file() except it reads configuration information from cnf.

The following flags are currently recognized:

CONF_MFLAGS_IGNORE_ERRORS
    Ignore errors returned by individual configuration modules. By default, the first module error is considered fatal and no further modules are loaded.

CONF_MFLAGS_SILENT
    Do not add any error information. By default, all module errors add error information to the error queue.

CONF_MFLAGS_NO_DSO
    Disable loading of configuration modules from DSOs.

CONF_MFLAGS_IGNORE_MISSING_FILE
    Let CONF_modules_load_file() ignore missing configuration files. By default, a missing configuration file returns an error.

CONF_MFLAGS_DEFAULT_SECTION
    If appname is not NULL but does not exist, fall back to the default section "openssl_conf".

By using CONF_modules_load_file() 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 may continue. In other cases an application might consider a configuration file error fatal and exit immediately.

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.

RETURN VALUES
These functions 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 (this will always be zero or negative).

FILES
/etc/ssl/openssl.cnf
    standard configuration file

EXAMPLES
Load a configuration file and print out any errors and exit (missing file 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 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 custom configuration file and section, only print warnings on error, missing configuration file ignored:

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

Load and parse configuration 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(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_init_crypto(3)

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