From 641c55342be8fcf87c9a2ec21c6e8245730c7aca Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Tue, 2 Mar 2004 12:46:30 +0000 Subject: [PATCH] More configuration docs. --- doc/crypto/CONF_modules_free.pod | 47 ++++++++++++++++ doc/crypto/CONF_modules_load_file.pod | 60 +++++++++++++++++++++ doc/crypto/OPENSSL_config.pod | 13 +++-- doc/crypto/OPENSSL_load_builtin_modules.pod | 51 ++++++++++++++++++ 4 files changed, 167 insertions(+), 4 deletions(-) create mode 100644 doc/crypto/CONF_modules_free.pod create mode 100644 doc/crypto/CONF_modules_load_file.pod create mode 100644 doc/crypto/OPENSSL_load_builtin_modules.pod diff --git a/doc/crypto/CONF_modules_free.pod b/doc/crypto/CONF_modules_free.pod new file mode 100644 index 0000000000..af8ae6a5c9 --- /dev/null +++ b/doc/crypto/CONF_modules_free.pod @@ -0,0 +1,47 @@ +=pod + +=head1 NAME + + CONF_modules_free, CONF_modules_load, CONF_modules_unload - + OpenSSL configuration cleanup functions + +=head1 SYNOPSIS + + #include + + void CONF_modules_free(void); + void CONF_modules_unload(int all); + void CONF_modules_finish(void); + +=head1 DESCRIPTION + +CONF_modules_free() closes down and frees up all memory allocated by all +configuration modules. + +CONF_modules_finish() calls each configuration modules B handler +to free up any configuration that module may have performed. + +CONF_modules_unload() finishes and unloads configuration modules. If +B is set to B<0> only modules loaded from DSOs will be unloads. If +B is B<1> all modules, including builtin modules will be unloaded. + +=head1 NOTES + +Normally applications will only call CONF_modules_free() at application to +tidy up any configuration performed. + +=head1 RETURN VALUE + +None of the functions return a value. + +=head1 SEE ALSO + +L, L, +L + +=head1 HISTORY + +CONF_modules_free(), CONF_modules_unload(), and CONF_modules_finish() +first appeared in OpenSSL 0.9.7. + +=cut diff --git a/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod new file mode 100644 index 0000000000..9965d69bf2 --- /dev/null +++ b/doc/crypto/CONF_modules_load_file.pod @@ -0,0 +1,60 @@ +=pod + +=head1 NAME + + CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions + +=head1 SYNOPSIS + + #include + + int CONF_modules_load_file(const char *filename, const char *appname, + unsigned long flags); + int CONF_modules_load(const CONF *cnf, const char *appname, + unsigned long flags); + +=head1 DESCRIPTION + +The function CONF_modules_load_file() configures OpenSSL using file +B and application name B. If B is NULL +the standard OpenSSL configuration file is used. If B is +NULL the standard OpenSSL application name B is used. +The behaviour can be cutomized using B. + +CONF_modules_load() is idential to CONF_modules_load_file() except it +read configuration information from B. + +=head1 NOTES + +The following B are currently recognized: + +B if set errors returned by individual +configuration modules are ignored. If not set the first module error is +considered fatal and no further modules are loads. + +Normally any modules errors will add error information to the error queue. If +B is set no error information is added. + +If B is set configuration module loading from DSOs is +disabled. + +B if set will make CONF_load_modules_file() +ignore missing configuration files. Normally a missing configuration file +return an error. + +=head1 RETURN VALUE + +These functions return 1 for success and a zero or negative value for +failure. If module errors are not ignored the return code will reflect the +return value of the failing module (this will always be zero or negative). + +=head1 SEE ALSO + +L, L, +L, L + +=head1 HISTORY + +CONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7. + +=cut diff --git a/doc/crypto/OPENSSL_config.pod b/doc/crypto/OPENSSL_config.pod index 18da16f3c3..16600620cc 100644 --- a/doc/crypto/OPENSSL_config.pod +++ b/doc/crypto/OPENSSL_config.pod @@ -2,7 +2,7 @@ =head1 NAME -OPENSSL_config, OPENSSL_no_config - minimal OpenSSL configuration +OPENSSL_config, OPENSSL_no_config - simple OpenSSL configuration functions =head1 SYNOPSIS @@ -32,7 +32,8 @@ 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 #define'd. +preprocessor symbol B #define'd. In this way configuration +can be added without source changes. The environment variable B can be set to specify the location of the configuration file. @@ -51,6 +52,9 @@ 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. +Applications should free up configuration at application closedown by calling +CONF_modules_free(). + =head1 RESTRICTIONS The OPENSSL_config() function is designed to be a very simple "call it and @@ -59,7 +63,7 @@ all errors silently and it can only load from the standard configuration file location for example. It is however B better than nothing. Applications which need finer -control over the configuration functionality should use the configuration +control over their configuration functionality should use the configuration functions such as CONF_load_modules() directly. =head1 RETURN VALUES @@ -68,7 +72,8 @@ Neither OPENSSL_config() nor OPENSSL_no_config() return a value. =head1 SEE ALSO -L +L, L, +L =head1 HISTORY diff --git a/doc/crypto/OPENSSL_load_builtin_modules.pod b/doc/crypto/OPENSSL_load_builtin_modules.pod new file mode 100644 index 0000000000..f14dfaf005 --- /dev/null +++ b/doc/crypto/OPENSSL_load_builtin_modules.pod @@ -0,0 +1,51 @@ +=pod + +=head1 NAME + +OPENSSL_load_builtin_modules - add standard configuration modules + +=head1 SYNOPSIS + + #include + + void OPENSSL_load_builtin_modules(void); + void ASN1_add_oid_module(void); + ENGINE_add_conf_module(); + +=head1 DESCRIPTION + +The function OPENSSL_load_builtin_modules() adds all the standard OpenSSL +configuration modules to the internal list. They can then be used by the +OpenSSL configuration code. + +ASN1_add_oid_module() adds just the ASN1 OBJECT module. + +ENGINE_add_conf_module() adds just the ENGINE configuration module. + +=head1 NOTES + +If the simple configuration function OPENSSL_config() is called then +OPENSSL_load_builtin_modules() is called automatically. + +Applications which use the configuration functions directly will need to +call OPENSSL_load_builtin_modules() themselves I any other +configuration code. + +Applications should call OPENSSL_load_builtin_modules() to load all +configuration modules instead of adding modules selectively: otherwise +functionality may be missing from the application if an when new +modules are added. + +=head1 RETURN VALUE + +None of the functions return a value. + +=head1 SEE ALSO + +L, L + +=head1 HISTORY + +These functions first appeared in OpenSSL 0.9.7. + +=cut -- 2.25.1