diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2004-03-02 01:01:11 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2004-03-02 01:01:11 +0000 |
commit | 5a8922aed50153592f8976b4c8a57c61f28363f0 (patch) | |
tree | 606cc1cbfe67a3d96d0e23837099ef3f6c783b13 /doc | |
parent | f2c18125607f0871df4cb5dfbeaf830f57811184 (diff) |
Documentation of the KISS autoconfig functions.
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/OPENSSL_config.pod | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod new file mode 100644 index 0000000000..18da16f3c3 --- /dev/null +++ b/doc/crypto/OPENSSL_config.pod @@ -0,0 +1,77 @@ +=pod + +=head1 NAME + +OPENSSL_config, OPENSSL_no_config - minimal OpenSSL configuration + +=head1 SYNOPSIS + + #include <openssl/conf.h> + + void OPENSSL_config(const char *config_name); + void OPENSSL_no_config(void); + +=head1 DESCRIPTION + +OPENSSL_config() configures OpenSSL using the standard B<openssl.cnf> +configuration file name using B<config_name>. If B<config_name> is NULL then +the default name B<openssl_conf> will be used. Any errors are ignored. Further +calls to OPENSSL_config() will have no effect. The configuration file format +is documented in the L<conf(5)|conf(5)> manual page. + +OPENSSL_no_config() disables configuration. If called before OPENSSL_config() +no configuration takes place. + +=head1 NOTES + +It is B<strongly> recommended that B<all> new applications call OPENSSL_config() +or the more sophisticated functions such as CONF_modules_load() during +initialization (that is before starting any threads). By doing this +an application does not need to keep track of all configuration options +and some new functionality can be supported automatically. + +It is also possible to automatically call OPENSSL_config() when an application +calls OPENSSL_add_all_algorithms() by compiling an application with the +preprocessor symbol B<OPENSSL_LOAD_CONF> #define'd. + +The environment variable B<OPENSSL_CONFIG> can be set to specify the location +of the configuration file. + +Currently ASN1 OBJECTs and ENGINE configuration can be performed future +versions of OpenSSL will add new configuration options. + +There are several reasons why calling the OpenSSL configuration routines is +advisable. For example new ENGINE functionality was added to OpenSSL 0.9.7. +In OpenSSL 0.9.7 control functions can be supported by ENGINEs, this can be +used (among other things) to load dynamic ENGINEs from shared libraries (DSOs). +However very few applications currently support the control interface and so +very few can load and use dynamic ENGINEs. Equally in future more sophisticated +ENGINEs will require certain control operations to customize them. If an +application calls OPENSSL_config() it doesn't need to know or care about +ENGINE control operations because they can be performed by editing a +configuration file. + +=head1 RESTRICTIONS + +The OPENSSL_config() function is designed to be a very simple "call it and +forget it" function. As a result its behaviour is somewhat limited. It ignores +all errors silently and it can only load from the standard configuration file +location for example. + +It is however B<much> better than nothing. Applications which need finer +control over the configuration functionality should use the configuration +functions such as CONF_load_modules() directly. + +=head1 RETURN VALUES + +Neither OPENSSL_config() nor OPENSSL_no_config() return a value. + +=head1 SEE ALSO + +L<conf(5)|conf(5)> + +=head1 HISTORY + +OPENSSL_config() and OPENSSL_no_config() first appeared in OpenSSL 0.9.7 + +=cut |