| blob | 620787b4f1c6f6139f1873af4cc24dccc3d44e99 |
1 .\" $OpenBSD: CONF_modules_load_file.3,v 1.5 2016/12/11 18:06:09 schwarze Exp $
2 .\" OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
3 .\"
4 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
5 .\" Copyright (c) 2000, 2015 The OpenSSL Project. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in
16 .\" the documentation and/or other materials provided with the
17 .\" distribution.
18 .\"
19 .\" 3. All advertising materials mentioning features or use of this
20 .\" software must display the following acknowledgment:
21 .\" "This product includes software developed by the OpenSSL Project
22 .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
23 .\"
24 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
25 .\" endorse or promote products derived from this software without
26 .\" prior written permission. For written permission, please contact
27 .\" openssl-core@openssl.org.
28 .\"
29 .\" 5. Products derived from this software may not be called "OpenSSL"
30 .\" nor may "OpenSSL" appear in their names without prior written
31 .\" permission of the OpenSSL Project.
32 .\"
33 .\" 6. Redistributions of any form whatsoever must retain the following
34 .\" acknowledgment:
35 .\" "This product includes software developed by the OpenSSL Project
36 .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
37 .\"
38 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
39 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
40 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
41 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
42 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
43 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
44 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
45 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
46 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
47 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
48 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
50 .\"
51 .Dd $Mdocdate: December 11 2016 $
52 .Dt CONF_MODULES_LOAD_FILE 3
53 .Os
54 .Sh NAME
55 .Nm CONF_modules_load_file ,
56 .Nm CONF_modules_load
57 .Nd OpenSSL configuration functions
58 .Sh SYNOPSIS
59 .In openssl/conf.h
60 .Ft int
61 .Fo CONF_modules_load_file
62 .Fa "const char *filename"
63 .Fa "const char *appname"
64 .Fa "unsigned long flags"
65 .Fc
66 .Ft int
67 .Fo CONF_modules_load
68 .Fa "const CONF *cnf"
69 .Fa "const char *appname"
70 .Fa "unsigned long flags"
71 .Fc
72 .Sh DESCRIPTION
73 The function
74 .Fn CONF_modules_load_file
75 configures OpenSSL using the file
76 .Fa filename
77 in
78 .Xr openssl.cnf 5
79 format and the application name
80 .Fa appname .
81 If
82 .Fa filename
83 is
84 .Dv NULL ,
85 the standard OpenSSL configuration file
86 .Pa /etc/ssl/openssl.cnf
87 is used.
88 If
89 .Fa appname
90 is
91 .Dv NULL ,
92 the standard OpenSSL application name
93 .Qq openssl_conf
94 is used.
95 The behaviour can be customized using
96 .Fa flags .
97 .Pp
98 .Fn CONF_modules_load
99 is identical to
100 .Fn CONF_modules_load_file
101 except it reads configuration information from
102 .Fa cnf .
103 .Pp
104 The following
105 .Fa flags
106 are currently recognized:
107 .Bl -tag -width Ds
108 .It Dv CONF_MFLAGS_IGNORE_ERRORS
109 Ignore errors returned by individual configuration modules.
110 By default, the first module error is considered fatal and no further
111 modules are loaded.
112 .It Dv CONF_MFLAGS_SILENT
113 Do not add any error information.
114 By default, all module errors add error information to the error queue.
115 .It Dv CONF_MFLAGS_NO_DSO
116 Disable loading of configuration modules from DSOs.
117 .It Dv CONF_MFLAGS_IGNORE_MISSING_FILE
118 Let
119 .Fn CONF_modules_load_file
120 ignore missing configuration files.
121 By default, a missing configuration file returns an error.
122 .It CONF_MFLAGS_DEFAULT_SECTION
123 If
124 .Fa appname
125 is not
126 .Dv NULL
127 but does not exist, fall back to the default section
128 .Qq openssl_conf .
129 .El
130 .Pp
131 By using
132 .Fn CONF_modules_load_file
133 with appropriate flags, an application can customise application
134 configuration to best suit its needs.
135 In some cases the use of a configuration file is optional and its
136 absence is not an error: in this case
137 .Dv CONF_MFLAGS_IGNORE_MISSING_FILE
138 would be set.
139 .Pp
140 Errors during configuration may also be handled differently by
141 different applications.
142 For example in some cases an error may simply print out a warning
143 message and the application may continue.
144 In other cases an application might consider a configuration file
145 error fatal and exit immediately.
146 .Pp
147 Applications can use the
148 .Fn CONF_modules_load
149 function if they wish to load a configuration file themselves and
150 have finer control over how errors are treated.
151 .Sh RETURN VALUES
152 These functions return 1 for success and zero or a negative value for
153 failure.
154 If module errors are not ignored, the return code will reflect the return
155 value of the failing module (this will always be zero or negative).
156 .Sh FILES
157 .Bl -tag -width /etc/ssl/openssl.cnf -compact
158 .It Pa /etc/ssl/openssl.cnf
159 standard configuration file
160 .El
161 .Sh EXAMPLES
162 Load a configuration file and print out any errors and exit (missing
163 file considered fatal):
164 .Bd -literal
165 if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
166 fprintf(stderr, "FATAL: error loading configuration file\n");
167 ERR_print_errors_fp(stderr);
168 exit(1);
169 }
170 .Ed
171 .Pp
172 Load default configuration file using the section indicated
173 by "myapp", tolerate missing files, but exit on other errors:
174 .Bd -literal
175 if (CONF_modules_load_file(NULL, "myapp",
176 CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
177 fprintf(stderr, "FATAL: error loading configuration file\n");
178 ERR_print_errors_fp(stderr);
179 exit(1);
180 }
181 .Ed
182 .Pp
183 Load custom configuration file and section, only print warnings on
184 error, missing configuration file ignored:
185 .Bd -literal
186 if (CONF_modules_load_file("/something/app.cnf", "myapp",
187 CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
188 fprintf(stderr, "WARNING: error loading configuration file\n");
189 ERR_print_errors_fp(stderr);
190 }
191 .Ed
192 .Pp
193 Load and parse configuration file manually, custom error handling:
194 .Bd -literal
195 FILE *fp;
196 CONF *cnf = NULL;
197 long eline;
199 fp = fopen("/somepath/app.cnf", "r");
200 if (fp == NULL) {
201 fprintf(stderr, "Error opening configuration file\n");
202 /* Other missing configuration file behaviour */
203 } else {
204 cnf = NCONF_new(NULL);
205 if (NCONF_load_fp(cnf, fp, &eline) == 0) {
206 fprintf(stderr, "Error on line %ld of configuration file\n",
207 eline);
208 ERR_print_errors_fp(stderr);
209 /* Other malformed configuration file behaviour */
210 } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
211 fprintf(stderr, "Error configuring application\n");
212 ERR_print_errors_fp(stderr);
213 /* Other configuration error behaviour */
214 }
215 fclose(fp);
216 NCONF_free(cnf);
217 }
218 .Ed
219 .Sh SEE ALSO
220 .Xr CONF_modules_free 3 ,
221 .Xr ERR 3 ,
222 .Xr OPENSSL_config 3
223 .Sh HISTORY
224 .Fn CONF_modules_load_file
225 and
226 .Fn CONF_modules_load
227 first appeared in OpenSSL 0.9.7.