CONF_modules_load_file_ex(3ossl)

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

NAME

6       CONF_get1_default_config_file, CONF_modules_load_file_ex,
7       CONF_modules_load_file, CONF_modules_load - OpenSSL configuration
8       functions
9

SYNOPSIS

11        #include <openssl/conf.h>
12
13        char *CONF_get1_default_config_file(void);
14        int CONF_modules_load_file_ex(OSSL_LIB_CTX *libctx, const char *filename,
15                                      const char *appname, unsigned long flags);
16        int CONF_modules_load_file(const char *filename, const char *appname,
17                                   unsigned long flags);
18        int CONF_modules_load(const CONF *cnf, const char *appname,
19                              unsigned long flags);
20

DESCRIPTION

22       The function CONF_get1_default_config_file() determines the default
23       configuration file pathname as follows.  If the OPENSSL_CONF
24       environment variable is set its value is returned.  Else the function
25       returns the path obtained using X509_get_default_cert_area(3) with the
26       filename "openssl.cnf" appended.  The caller is responsible for freeing
27       any string returned.
28
29       The function CONF_modules_load_file_ex() configures OpenSSL using
30       library context libctx file filename and application name appname.  If
31       filename is NULL the standard OpenSSL configuration file is used as
32       determined by calling CONF_get1_default_config_file().  If appname is
33       NULL the standard OpenSSL application name openssl_conf is used.  The
34       behaviour can be customized using flags. Note that, the error
35       suppressing can be overriden by config_diagnostics as described in
36       config(5).
37
38       CONF_modules_load_file() is the same as CONF_modules_load_file_ex() but
39       has a NULL library context.
40
41       CONF_modules_load() is identical to CONF_modules_load_file() except it
42       reads configuration information from cnf.
43

NOTES

45       The following flags are currently recognized:
46
47       If CONF_MFLAGS_IGNORE_ERRORS is set errors returned by individual
48       configuration modules are ignored. If not set the first module error is
49       considered fatal and no further modules are loaded.
50
51       Normally any modules errors will add error information to the error
52       queue. If CONF_MFLAGS_SILENT is set no error information is added.
53
54       If CONF_MFLAGS_IGNORE_RETURN_CODES is set the function unconditionally
55       returns success.  This is used by default in OPENSSL_init_crypto(3) to
56       ignore any errors in the default system-wide configuration file, as
57       having all OpenSSL applications fail to start when there are
58       potentially minor issues in the file is too risky.  Applications
59       calling CONF_modules_load_file_ex explicitly should not generally set
60       this flag.
61
62       If CONF_MFLAGS_NO_DSO is set configuration module loading from DSOs is
63       disabled.
64
65       CONF_MFLAGS_IGNORE_MISSING_FILE if set will make
66       CONF_load_modules_file() ignore missing configuration files. Normally a
67       missing configuration file return an error.
68
69       CONF_MFLAGS_DEFAULT_SECTION if set and appname is not NULL will use the
70       default section pointed to by openssl_conf if appname does not exist.
71
72       By using CONF_modules_load_file_ex() with appropriate flags an
73       application can customise application configuration to best suit its
74       needs.  In some cases the use of a configuration file is optional and
75       its absence is not an error: in this case
76       CONF_MFLAGS_IGNORE_MISSING_FILE would be set.
77
78       Errors during configuration may also be handled differently by
79       different applications. For example in some cases an error may simply
80       print out a warning message and the application continue. In other
81       cases an application might consider a configuration file error as fatal
82       and exit immediately.
83
84       Applications can use the CONF_modules_load() function if they wish to
85       load a configuration file themselves and have finer control over how
86       errors are treated.
87

RETURN VALUES

89       These functions return 1 for success and a zero or negative value for
90       failure. If module errors are not ignored the return code will reflect
91       the return value of the failing module (this will always be zero or
92       negative).
93

EXAMPLES

95       Load a configuration file and print out any errors and exit (missing
96       file considered fatal):
97
98        if (CONF_modules_load_file_ex(libctx, NULL, NULL, 0) <= 0) {
99            fprintf(stderr, "FATAL: error loading configuration file\n");
100            ERR_print_errors_fp(stderr);
101            exit(1);
102        }
103
104       Load default configuration file using the section indicated by "myapp",
105       tolerate missing files, but exit on other errors:
106
107        if (CONF_modules_load_file_ex(NULL, NULL, "myapp",
108                                      CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
109            fprintf(stderr, "FATAL: error loading configuration file\n");
110            ERR_print_errors_fp(stderr);
111            exit(1);
112        }
113
114       Load custom configuration file and section, only print warnings on
115       error, missing configuration file ignored:
116
117        if (CONF_modules_load_file_ex(NULL, "/something/app.cnf", "myapp",
118                                      CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
119            fprintf(stderr, "WARNING: error loading configuration file\n");
120            ERR_print_errors_fp(stderr);
121        }
122
123       Load and parse configuration file manually, custom error handling:
124
125        FILE *fp;
126        CONF *cnf = NULL;
127        long eline;
128
129        fp = fopen("/somepath/app.cnf", "r");
130        if (fp == NULL) {
131            fprintf(stderr, "Error opening configuration file\n");
132            /* Other missing configuration file behaviour */
133        } else {
134            cnf = NCONF_new_ex(libctx, NULL);
135            if (NCONF_load_fp(cnf, fp, &eline) == 0) {
136                fprintf(stderr, "Error on line %ld of configuration file\n", eline);
137                ERR_print_errors_fp(stderr);
138                /* Other malformed configuration file behaviour */
139            } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
140                fprintf(stderr, "Error configuring application\n");
141                ERR_print_errors_fp(stderr);
142                /* Other configuration error behaviour */
143            }
144            fclose(fp);
145            NCONF_free(cnf);
146        }
147

COPYRIGHT

152       Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved.
153
154       Licensed under the Apache License 2.0 (the "License").  You may not use
155       this file except in compliance with the License.  You can obtain a copy
156       in the file LICENSE in the source distribution or at
157       <https://www.openssl.org/source/license.html>.
158
159
160
1613.0.5                             2022-11-01     CONF_MODULES_LOAD_FILE(3ossl)