summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/CONF_modules_load_file.3
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/CONF_modules_load_file.3')
-rw-r--r--src/lib/libcrypto/man/CONF_modules_load_file.3285
1 files changed, 0 insertions, 285 deletions
diff --git a/src/lib/libcrypto/man/CONF_modules_load_file.3 b/src/lib/libcrypto/man/CONF_modules_load_file.3
deleted file mode 100644
index bd419ef3e3..0000000000
--- a/src/lib/libcrypto/man/CONF_modules_load_file.3
+++ /dev/null
@@ -1,285 +0,0 @@
1.\" $OpenBSD: CONF_modules_load_file.3,v 1.10 2021/08/03 18:49:30 schwarze Exp $
2.\" full merge up to: e9b77246 Jan 20 19:58:49 2017 +0100
3.\" selective merge up to: d090fc00 Feb 26 13:11:10 2019 +0800
4.\"
5.\" This file is a derived work.
6.\" The changes are covered by the following Copyright and license:
7.\"
8.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
9.\"
10.\" Permission to use, copy, modify, and distribute this software for any
11.\" purpose with or without fee is hereby granted, provided that the above
12.\" copyright notice and this permission notice appear in all copies.
13.\"
14.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
15.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
16.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
17.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
18.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
19.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
20.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
21.\"
22.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
23.\" Copyright (c) 2000, 2015 The OpenSSL Project. All rights reserved.
24.\"
25.\" Redistribution and use in source and binary forms, with or without
26.\" modification, are permitted provided that the following conditions
27.\" are met:
28.\"
29.\" 1. Redistributions of source code must retain the above copyright
30.\" notice, this list of conditions and the following disclaimer.
31.\"
32.\" 2. Redistributions in binary form must reproduce the above copyright
33.\" notice, this list of conditions and the following disclaimer in
34.\" the documentation and/or other materials provided with the
35.\" distribution.
36.\"
37.\" 3. All advertising materials mentioning features or use of this
38.\" software must display the following acknowledgment:
39.\" "This product includes software developed by the OpenSSL Project
40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
41.\"
42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
43.\" endorse or promote products derived from this software without
44.\" prior written permission. For written permission, please contact
45.\" openssl-core@openssl.org.
46.\"
47.\" 5. Products derived from this software may not be called "OpenSSL"
48.\" nor may "OpenSSL" appear in their names without prior written
49.\" permission of the OpenSSL Project.
50.\"
51.\" 6. Redistributions of any form whatsoever must retain the following
52.\" acknowledgment:
53.\" "This product includes software developed by the OpenSSL Project
54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
55.\"
56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
67.\" OF THE POSSIBILITY OF SUCH DAMAGE.
68.\"
69.Dd $Mdocdate: August 3 2021 $
70.Dt CONF_MODULES_LOAD_FILE 3
71.Os
72.Sh NAME
73.Nm CONF_modules_load_file ,
74.Nm CONF_modules_load ,
75.Nm X509_get_default_cert_area
76.Nd OpenSSL configuration functions
77.Sh SYNOPSIS
78.In openssl/conf.h
79.Ft int
80.Fo CONF_modules_load_file
81.Fa "const char *filename"
82.Fa "const char *appname"
83.Fa "unsigned long flags"
84.Fc
85.Ft int
86.Fo CONF_modules_load
87.Fa "const CONF *cnf"
88.Fa "const char *appname"
89.Fa "unsigned long flags"
90.Fc
91.In openssl/x509.h
92.Ft const char *
93.Fn X509_get_default_cert_area void
94.Sh DESCRIPTION
95The function
96.Fn CONF_modules_load_file
97configures OpenSSL using the file
98.Fa filename
99in
100.Xr openssl.cnf 5
101format and the application name
102.Fa appname .
103If
104.Fa filename
105is
106.Dv NULL ,
107the standard OpenSSL configuration file
108.Pa /etc/ssl/openssl.cnf
109is used.
110If
111.Fa appname
112is
113.Dv NULL ,
114the standard OpenSSL application name
115.Qq openssl_conf
116is used.
117The behaviour can be customized using
118.Fa flags .
119.Pp
120See the
121.Sx EXAMPLES
122section for additional functions that may need to be called.
123Calling configuration functions in the right order for the intended
124effect can be tricky because many configuration functions internally
125call each other.
126.Pp
127.Fn CONF_modules_load
128is identical to
129.Fn CONF_modules_load_file
130except it reads configuration information from
131.Fa cnf .
132.Pp
133The following
134.Fa flags
135are currently recognized:
136.Bl -tag -width Ds
137.It Dv CONF_MFLAGS_IGNORE_ERRORS
138Ignore errors returned by individual configuration modules.
139By default, the first module error is considered fatal and no further
140modules are loaded.
141.It Dv CONF_MFLAGS_SILENT
142Do not add any error information.
143By default, all module errors add error information to the error queue.
144.It Dv CONF_MFLAGS_NO_DSO
145Disable loading of configuration modules from DSOs.
146.It Dv CONF_MFLAGS_IGNORE_MISSING_FILE
147Let
148.Fn CONF_modules_load_file
149ignore missing configuration files.
150By default, a missing configuration file returns an error.
151.It CONF_MFLAGS_DEFAULT_SECTION
152If
153.Fa appname
154is not
155.Dv NULL
156but does not exist, fall back to the default section
157.Qq openssl_conf .
158.El
159.Pp
160By using
161.Fn CONF_modules_load_file
162with appropriate flags, an application can customise application
163configuration to best suit its needs.
164In some cases the use of a configuration file is optional and its
165absence is not an error: in this case
166.Dv CONF_MFLAGS_IGNORE_MISSING_FILE
167would be set.
168.Pp
169Errors during configuration may also be handled differently by
170different applications.
171For example in some cases an error may simply print out a warning
172message and the application may continue.
173In other cases an application might consider a configuration file
174error fatal and exit immediately.
175.Pp
176Applications can use the
177.Fn CONF_modules_load
178function if they wish to load a configuration file themselves and
179have finer control over how errors are treated.
180.Sh RETURN VALUES
181.Fn CONF_modules_load_file
182and
183.Fn CONF_modules_load
184return 1 for success and zero or a negative value for failure.
185If module errors are not ignored, the return code will reflect the return
186value of the failing module (this will always be zero or negative).
187.Pp
188.Fn X509_get_default_cert_area
189returns a pointer to the constant string
190.Qq "/etc/ssl" .
191.Sh FILES
192.Bl -tag -width /etc/ssl/openssl.cnf -compact
193.It Pa /etc/ssl
194standard configuration directory
195.It Pa /etc/ssl/openssl.cnf
196standard configuration file
197.El
198.Sh EXAMPLES
199Load a configuration file and print out any errors and exit (missing
200file considered fatal):
201.Bd -literal
202if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
203 fprintf(stderr, "FATAL: error loading configuration file\en");
204 ERR_print_errors_fp(stderr);
205 exit(1);
206}
207.Ed
208.Pp
209Load default configuration file using the section indicated
210by "myapp", tolerate missing files, but exit on other errors:
211.Bd -literal
212if (CONF_modules_load_file(NULL, "myapp",
213 CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
214 fprintf(stderr, "FATAL: error loading configuration file\en");
215 ERR_print_errors_fp(stderr);
216 exit(1);
217}
218.Ed
219.Pp
220Load custom configuration file and section instead of the standard one,
221only print warnings on error, missing configuration file ignored:
222.Bd -literal
223OPENSSL_no_config();
224ENGINE_load_builtin_engines();
225OPENSSL_load_builtin_modules();
226if (CONF_modules_load_file("/something/app.cnf", "myapp",
227 CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
228 fprintf(stderr, "WARNING: error loading configuration file\en");
229 ERR_print_errors_fp(stderr);
230}
231.Ed
232.Pp
233In the previous example, the call to
234.Xr OPENSSL_no_config 3
235is required first to suppress automatic loading
236of the standard configuration file, and the calls to
237.Xr ENGINE_load_builtin_engines 3
238and
239.Xr OPENSSL_load_builtin_modules 3
240are needed so that the configuration of builtin modules and engines
241is also loaded in addition to the configuration of
242.Qq myapp .
243.Pp
244Load and parse configuration file manually, custom error handling:
245.Bd -literal
246FILE *fp;
247CONF *cnf = NULL;
248long eline;
249
250fp = fopen("/somepath/app.cnf", "r");
251if (fp == NULL) {
252 fprintf(stderr, "Error opening configuration file\en");
253 /* Other missing configuration file behaviour */
254} else {
255 cnf = NCONF_new(NULL);
256 if (NCONF_load_fp(cnf, fp, &eline) == 0) {
257 fprintf(stderr, "Error on line %ld of configuration file\en",
258 eline);
259 ERR_print_errors_fp(stderr);
260 /* Other malformed configuration file behaviour */
261 } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
262 fprintf(stderr, "Error configuring application\en");
263 ERR_print_errors_fp(stderr);
264 /* Other configuration error behaviour */
265 }
266 fclose(fp);
267 NCONF_free(cnf);
268}
269.Ed
270.Sh SEE ALSO
271.Xr CONF_modules_free 3 ,
272.Xr ENGINE_load_builtin_engines 3 ,
273.Xr ERR 3 ,
274.Xr OPENSSL_config 3 ,
275.Xr OPENSSL_load_builtin_modules 3
276.Sh HISTORY
277.Fn X509_get_default_cert_area
278first appeared in SSLeay 0.4.1 and has been available since
279.Ox 2.4 .
280.Pp
281.Fn CONF_modules_load_file
282and
283.Fn CONF_modules_load
284first appeared in OpenSSL 0.9.7 and have been available since
285.Ox 3.2 .
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2026-02-14 04:18:49 +0000