1CONF_MODULES_LOAD_FILE(3)           OpenSSL          CONF_MODULES_LOAD_FILE(3)
2
3
4

NAME

6       CONF_modules_load_file, CONF_modules_load - OpenSSL configuration
7       functions
8

SYNOPSIS

10        #include <openssl/conf.h>
11
12        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

DESCRIPTION

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
24       CONF_modules_load() is identical to CONF_modules_load_file() except it
25       reads configuration information from cnf.
26

NOTES

28       The following flags are currently recognized:
29
30       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
34       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
37       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
45       If CONF_MFLAGS_NO_DSO is set configuration module loading from DSOs is
46       disabled.
47
48       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
52       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
55       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
61       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
67       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

RETURN VALUES

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

EXAMPLES

78       Load a configuration file and print out any errors and exit (missing
79       file considered fatal):
80
81        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
87       Load default configuration file using the section indicated by "myapp",
88       tolerate missing files, but exit on other errors:
89
90        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
97       Load custom configuration file and section, only print warnings on
98       error, missing configuration file ignored:
99
100        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
106       Load and parse configuration file manually, custom error handling:
107
108        FILE *fp;
109        CONF *cnf = NULL;
110        long eline;
111
112        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

SEE ALSO

132       config(5), OPENSSL_config(3)
133
135       Copyright 2004-2019 The OpenSSL Project Authors. All Rights Reserved.
136
137       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>.
141
142
143
1441.1.1q                            2023-02-06         CONF_MODULES_LOAD_FILE(3)
Impressum