1.\" $OpenBSD: OPENSSL_config.3,v 1.6 2017/07/06 15:42:04 schwarze Exp $ 2.\" OpenSSL ab6577a4 May 14 21:07:51 2014 +0100 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2000, 2004, 2005 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: July 6 2017 $ 52.Dt OPENSSL_CONFIG 3 53.Os 54.Sh NAME 55.Nm OPENSSL_config , 56.Nm OPENSSL_no_config 57.Nd simple OpenSSL configuration functions 58.Sh SYNOPSIS 59.In openssl/conf.h 60.Ft void 61.Fo OPENSSL_config 62.Fa "const char *config_name" 63.Fc 64.Ft void 65.Fn OPENSSL_no_config void 66.Sh DESCRIPTION 67.Fn OPENSSL_config 68configures OpenSSL using the standard 69.Xr openssl.cnf 5 70configuration file name using 71.Fa config_name . 72If 73.Fa config_name 74is 75.Dv NULL 76then the default name 77.Sy openssl_conf 78will be used. 79Any errors are ignored. 80Further calls to 81.Fn OPENSSL_config 82will have no effect. 83.Pp 84.Fn OPENSSL_no_config 85disables configuration. 86If called before 87.Fn OPENSSL_config , 88no configuration takes place. 89.Pp 90It is 91.Sy strongly 92recommended that 93.Sy all 94new applications call 95.Fn OPENSSL_config 96or the more sophisticated functions such as 97.Xr CONF_modules_load 3 98during initialization (that is before starting any threads). 99By doing this, an application does not need to keep track of all 100configuration options and some new functionality can be supported 101automatically. 102.Pp 103It is also possible to automatically call 104.Fn OPENSSL_config 105when an application calls 106.Xr OpenSSL_add_all_algorithms 3 107by compiling an application with the preprocessor symbol 108.Dv OPENSSL_LOAD_CONF 109#define'd. 110In this way configuration can be added without source changes. 111.Pp 112The environment variable 113.Ev OPENSSL_CONF 114can be set to specify the location of the configuration file. 115.Pp 116Currently ASN.1 OBJECT and ENGINE configuration can be performed. 117.Pp 118There are several reasons why calling the OpenSSL configuration routines 119is advisable. 120For example new ENGINE functionality was added to OpenSSL 0.9.7. 121In OpenSSL 0.9.7 control functions can be supported by ENGINEs which can be 122used (among other things) to load dynamic ENGINEs from shared libraries 123(DSOs). 124However very few applications currently support the control interface 125and so very few can load and use dynamic ENGINEs. 126Equally in future more sophisticated ENGINEs will require certain 127control operations to customize them. 128If an application calls 129.Fn OPENSSL_config 130it doesn't need to know or care about ENGINE control operations because 131they can be performed by editing a configuration file. 132.Pp 133Applications should free up configuration at application closedown by 134calling 135.Xr CONF_modules_free 3 . 136.Sh RETURN VALUES 137Neither 138.Fn OPENSSL_config 139nor 140.Fn OPENSSL_no_config 141return a value. 142.Sh FILES 143.Bl -tag -width /etc/ssl/openssl.cnf -compact 144.It Pa /etc/ssl/openssl.cnf 145standard configuration file 146.El 147.Sh SEE ALSO 148.Xr CONF_modules_free 3 , 149.Xr CONF_modules_load 3 , 150.Xr openssl.cnf 5 151.Sh HISTORY 152.Fn OPENSSL_config 153and 154.Fn OPENSSL_no_config 155first appeared in OpenSSL 0.9.7. 156.Sh CAVEATS 157The 158.Fn OPENSSL_config 159function is designed to be a very simple "call it and forget it" 160function. 161As a result its behaviour is somewhat limited. 162It ignores all errors silently and it can only load from the standard 163configuration file location for example. 164.Pp 165It is however 166.Sy much 167better than nothing. 168Applications which need finer control over their configuration 169functionality should use the configuration functions such as 170.Xr CONF_modules_load 3 171directly. 172