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
HISTORY
CONF_modules_load_file
() and
CONF_modules_load
() first appeared in OpenSSL
0.9.7.