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 73The function 74.Fn CONF_modules_load_file 75configures OpenSSL using the file 76.Fa filename 77in 78.Xr openssl.cnf 5 79format and the application name 80.Fa appname . 81If 82.Fa filename 83is 84.Dv NULL , 85the standard OpenSSL configuration file 86.Pa /etc/ssl/openssl.cnf 87is used. 88If 89.Fa appname 90is 91.Dv NULL , 92the standard OpenSSL application name 93.Qq openssl_conf 94is used. 95The behaviour can be customized using 96.Fa flags . 97.Pp 98.Fn CONF_modules_load 99is identical to 100.Fn CONF_modules_load_file 101except it reads configuration information from 102.Fa cnf . 103.Pp 104The following 105.Fa flags 106are currently recognized: 107.Bl -tag -width Ds 108.It Dv CONF_MFLAGS_IGNORE_ERRORS 109Ignore errors returned by individual configuration modules. 110By default, the first module error is considered fatal and no further 111modules are loaded. 112.It Dv CONF_MFLAGS_SILENT 113Do not add any error information. 114By default, all module errors add error information to the error queue. 115.It Dv CONF_MFLAGS_NO_DSO 116Disable loading of configuration modules from DSOs. 117.It Dv CONF_MFLAGS_IGNORE_MISSING_FILE 118Let 119.Fn CONF_modules_load_file 120ignore missing configuration files. 121By default, a missing configuration file returns an error. 122.It CONF_MFLAGS_DEFAULT_SECTION 123If 124.Fa appname 125is not 126.Dv NULL 127but does not exist, fall back to the default section 128.Qq openssl_conf . 129.El 130.Pp 131By using 132.Fn CONF_modules_load_file 133with appropriate flags, an application can customise application 134configuration to best suit its needs. 135In some cases the use of a configuration file is optional and its 136absence is not an error: in this case 137.Dv CONF_MFLAGS_IGNORE_MISSING_FILE 138would be set. 139.Pp 140Errors during configuration may also be handled differently by 141different applications. 142For example in some cases an error may simply print out a warning 143message and the application may continue. 144In other cases an application might consider a configuration file 145error fatal and exit immediately. 146.Pp 147Applications can use the 148.Fn CONF_modules_load 149function if they wish to load a configuration file themselves and 150have finer control over how errors are treated. 151.Sh RETURN VALUES 152These functions return 1 for success and zero or a negative value for 153failure. 154If module errors are not ignored, the return code will reflect the return 155value 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 159standard configuration file 160.El 161.Sh EXAMPLES 162Load a configuration file and print out any errors and exit (missing 163file considered fatal): 164.Bd -literal 165if (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 172Load default configuration file using the section indicated 173by "myapp", tolerate missing files, but exit on other errors: 174.Bd -literal 175if (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 183Load custom configuration file and section, only print warnings on 184error, missing configuration file ignored: 185.Bd -literal 186if (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 193Load and parse configuration file manually, custom error handling: 194.Bd -literal 195FILE *fp; 196CONF *cnf = NULL; 197long eline; 198 199fp = fopen("/somepath/app.cnf", "r"); 200if (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 225and 226.Fn CONF_modules_load 227first appeared in OpenSSL 0.9.7. 228