1CONF_MODULES_LOAD_FILE(3) OpenSSL CONF_MODULES_LOAD_FILE(3)
2
6 CONF_modules_load_file, CONF_modules_load - OpenSSL configuration
7 functions
8
10 #include <openssl/conf.h>
11 int CONF_modules_load_file(const char *filename, const char *appname,
13 unsigned long flags);
14 int CONF_modules_load(const CONF *cnf, const char *appname,
15 unsigned long flags);
16
18 The function CONF_modules_load_file() configures OpenSSL using file
19 filename and application name appname. If filename is NULL the standard
20 OpenSSL configuration file is used. If appname is NULL the standard
21 OpenSSL application name openssl_conf is used. The behaviour can be
22 customized using flags.
23 CONF_modules_load() is identical to CONF_modules_load_file() except it
25 reads configuration information from cnf.
26
28 The following flags are currently recognized:
29 If CONF_MFLAGS_IGNORE_ERRORS is set errors returned by individual
31 configuration modules are ignored. If not set the first module error is
32 considered fatal and no further modules are loaded.
33 Normally any modules errors will add error information to the error
35 queue. If CONF_MFLAGS_SILENT is set no error information is added.
36 If CONF_MFLAGS_IGNORE_RETURN_CODES is set the function unconditionally
38 returns success. This is used by default in OPENSSL_init_crypto(3) to
39 ignore any errors in the default system-wide configuration file, as
40 having all OpenSSL applications fail to start when there are
41 potentially minor issues in the file is too risky. Applications
42 calling CONF_modules_load_file explicitly should not generally set this
43 flag.
44 If CONF_MFLAGS_NO_DSO is set configuration module loading from DSOs is
46 disabled.
47 CONF_MFLAGS_IGNORE_MISSING_FILE if set will make
49 CONF_load_modules_file() ignore missing configuration files. Normally a
50 missing configuration file return an error.
51 CONF_MFLAGS_DEFAULT_SECTION if set and appname is not NULL will use the
53 default section pointed to by openssl_conf if appname does not exist.
54 By using CONF_modules_load_file() with appropriate flags an application
56 can customise application configuration to best suit its needs. In some
57 cases the use of a configuration file is optional and its absence is
58 not an error: in this case CONF_MFLAGS_IGNORE_MISSING_FILE would be
59 set.
60 Errors during configuration may also be handled differently by
62 different applications. For example in some cases an error may simply
63 print out a warning message and the application continue. In other
64 cases an application might consider a configuration file error as fatal
65 and exit immediately.
66 Applications can use the CONF_modules_load() function if they wish to
68 load a configuration file themselves and have finer control over how
69 errors are treated.
70
72 These functions return 1 for success and a zero or negative value for
73 failure. If module errors are not ignored the return code will reflect
74 the return value of the failing module (this will always be zero or
75 negative).
76
78 Load a configuration file and print out any errors and exit (missing
79 file considered fatal):
80 if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
82 fprintf(stderr, "FATAL: error loading configuration file\n");
83 ERR_print_errors_fp(stderr);
84 exit(1);
85 }
86 Load default configuration file using the section indicated by "myapp",
88 tolerate missing files, but exit on other errors:
89 if (CONF_modules_load_file(NULL, "myapp",
91 CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
92 fprintf(stderr, "FATAL: error loading configuration file\n");
93 ERR_print_errors_fp(stderr);
94 exit(1);
95 }
96 Load custom configuration file and section, only print warnings on
98 error, missing configuration file ignored:
99 if (CONF_modules_load_file("/something/app.cnf", "myapp",
101 CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
102 fprintf(stderr, "WARNING: error loading configuration file\n");
103 ERR_print_errors_fp(stderr);
104 }
105 Load and parse configuration file manually, custom error handling:
107 FILE *fp;
109 CONF *cnf = NULL;
110 long eline;
111 fp = fopen("/somepath/app.cnf", "r");
113 if (fp == NULL) {
114 fprintf(stderr, "Error opening configuration file\n");
115 /* Other missing configuration file behaviour */
116 } else {
117 cnf = NCONF_new(NULL);
118 if (NCONF_load_fp(cnf, fp, &eline) == 0) {
119 fprintf(stderr, "Error on line %ld of configuration file\n", eline);
120 ERR_print_errors_fp(stderr);
121 /* Other malformed configuration file behaviour */
122 } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
123 fprintf(stderr, "Error configuring application\n");
124 ERR_print_errors_fp(stderr);
125 /* Other configuration error behaviour */
126 }
127 fclose(fp);
128 NCONF_free(cnf);
129 }
130
132 config(5), OPENSSL_config(3)
133
135 Copyright 2004-2019 The OpenSSL Project Authors. All Rights Reserved.
136 Licensed under the OpenSSL license (the "License"). You may not use
138 this file except in compliance with the License. You can obtain a copy
139 in the file LICENSE in the source distribution or at
140 <https://www.openssl.org/source/license.html>.
1411.1.1i 2021-01-26 CONF_MODULES_LOAD_FILE(3)