OpenBSD manual page server

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 file0);
	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 file0);
	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 file0);
	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 file0);
	/* 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 file0,
		    eline);
		ERR_print_errors_fp(stderr);
		/* Other malformed configuration file behaviour */
	} else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
		fprintf(stderr, "Error configuring application0);
		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.