]>
Commit | Line | Data |
---|---|---|
f82bb9cb DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
1bc74519 | 5 | CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions |
f82bb9cb DSH |
6 | |
7 | =head1 SYNOPSIS | |
8 | ||
9 | #include <openssl/conf.h> | |
10 | ||
11 | int CONF_modules_load_file(const char *filename, const char *appname, | |
e9b77246 | 12 | unsigned long flags); |
f82bb9cb | 13 | int CONF_modules_load(const CONF *cnf, const char *appname, |
e9b77246 | 14 | unsigned long flags); |
f82bb9cb DSH |
15 | |
16 | =head1 DESCRIPTION | |
17 | ||
18 | The function CONF_modules_load_file() configures OpenSSL using file | |
19 | B<filename> and application name B<appname>. If B<filename> is NULL | |
20 | the standard OpenSSL configuration file is used. If B<appname> is | |
21 | NULL the standard OpenSSL application name B<openssl_conf> is used. | |
186bb907 | 22 | The behaviour can be customized using B<flags>. |
f82bb9cb | 23 | |
186bb907 | 24 | CONF_modules_load() is identical to CONF_modules_load_file() except it |
3d764db7 | 25 | reads configuration information from B<cnf>. |
f82bb9cb DSH |
26 | |
27 | =head1 NOTES | |
28 | ||
29 | The following B<flags> are currently recognized: | |
30 | ||
31 | B<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual | |
32 | configuration modules are ignored. If not set the first module error is | |
3d764db7 | 33 | considered fatal and no further modules are loaded. |
f82bb9cb DSH |
34 | |
35 | Normally any modules errors will add error information to the error queue. If | |
36 | B<CONF_MFLAGS_SILENT> is set no error information is added. | |
37 | ||
38 | If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is | |
39 | disabled. | |
40 | ||
41 | B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file() | |
42 | ignore missing configuration files. Normally a missing configuration file | |
43 | return an error. | |
44 | ||
3d764db7 DSH |
45 | B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the |
46 | default section pointed to by B<openssl_conf> if B<appname> does not exist. | |
47 | ||
3d764db7 DSH |
48 | By using CONF_modules_load_file() with appropriate flags an application can |
49 | customise application configuration to best suit its needs. In some cases the | |
50 | use of a configuration file is optional and its absence is not an error: in | |
51 | this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set. | |
52 | ||
53 | Errors during configuration may also be handled differently by different | |
54 | applications. For example in some cases an error may simply print out a warning | |
55 | message and the application continue. In other cases an application might | |
56 | consider a configuration file error as fatal and exit immediately. | |
57 | ||
58 | Applications can use the CONF_modules_load() function if they wish to load a | |
59 | configuration file themselves and have finer control over how errors are | |
60 | treated. | |
61 | ||
62 | =head1 EXAMPLES | |
63 | ||
64 | Load a configuration file and print out any errors and exit (missing file | |
65 | considered fatal): | |
66 | ||
67 | if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { | |
2947af32 BB |
68 | fprintf(stderr, "FATAL: error loading configuration file\n"); |
69 | ERR_print_errors_fp(stderr); | |
70 | exit(1); | |
3d764db7 DSH |
71 | } |
72 | ||
73 | Load default configuration file using the section indicated by "myapp", | |
74 | tolerate missing files, but exit on other errors: | |
75 | ||
76 | if (CONF_modules_load_file(NULL, "myapp", | |
77 | CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { | |
2947af32 BB |
78 | fprintf(stderr, "FATAL: error loading configuration file\n"); |
79 | ERR_print_errors_fp(stderr); | |
80 | exit(1); | |
3d764db7 DSH |
81 | } |
82 | ||
83 | Load custom configuration file and section, only print warnings on error, | |
84 | missing configuration file ignored: | |
85 | ||
86 | if (CONF_modules_load_file("/something/app.cnf", "myapp", | |
87 | CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { | |
2947af32 BB |
88 | fprintf(stderr, "WARNING: error loading configuration file\n"); |
89 | ERR_print_errors_fp(stderr); | |
3d764db7 DSH |
90 | } |
91 | ||
92 | Load and parse configuration file manually, custom error handling: | |
93 | ||
94 | FILE *fp; | |
95 | CONF *cnf = NULL; | |
96 | long eline; | |
e9b77246 | 97 | |
3d764db7 DSH |
98 | fp = fopen("/somepath/app.cnf", "r"); |
99 | if (fp == NULL) { | |
2947af32 BB |
100 | fprintf(stderr, "Error opening configuration file\n"); |
101 | /* Other missing configuration file behaviour */ | |
3d764db7 | 102 | } else { |
2947af32 BB |
103 | cnf = NCONF_new(NULL); |
104 | if (NCONF_load_fp(cnf, fp, &eline) == 0) { | |
105 | fprintf(stderr, "Error on line %ld of configuration file\n", eline); | |
106 | ERR_print_errors_fp(stderr); | |
107 | /* Other malformed configuration file behaviour */ | |
108 | } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { | |
109 | fprintf(stderr, "Error configuring application\n"); | |
110 | ERR_print_errors_fp(stderr); | |
111 | /* Other configuration error behaviour */ | |
112 | } | |
113 | fclose(fp); | |
114 | NCONF_free(cnf); | |
115 | } | |
3d764db7 DSH |
116 | |
117 | =head1 RETURN VALUES | |
f82bb9cb DSH |
118 | |
119 | These functions return 1 for success and a zero or negative value for | |
120 | failure. If module errors are not ignored the return code will reflect the | |
121 | return value of the failing module (this will always be zero or negative). | |
122 | ||
123 | =head1 SEE ALSO | |
124 | ||
9e183d22 | 125 | L<config(5)>, L<OPENSSL_config(3)> |
f82bb9cb | 126 | |
e2f92610 RS |
127 | =head1 COPYRIGHT |
128 | ||
73fb82b7 | 129 | Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 RS |
130 | |
131 | Licensed under the OpenSSL license (the "License"). You may not use | |
132 | this file except in compliance with the License. You can obtain a copy | |
133 | in the file LICENSE in the source distribution or at | |
134 | L<https://www.openssl.org/source/license.html>. | |
135 | ||
136 | =cut |