From c0d69ddb3323e45afba7a7f1608fb03f9a7d6fff Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Sun, 1 Mar 2015 15:25:39 +0000 Subject: [PATCH] additional configuration documentation Reviewed-by: Andy Polyakov (cherry picked from commit 3d764db7a24e3dca1a3ee57202ce3c818d592141) --- doc/apps/config.pod | 22 ++++++- doc/crypto/CONF_modules_load_file.pod | 87 +++++++++++++++++++++++++-- 2 files changed, 102 insertions(+), 7 deletions(-) diff --git a/doc/apps/config.pod b/doc/apps/config.pod index 25c5381b9d..d5cce54f44 100644 --- a/doc/apps/config.pod +++ b/doc/apps/config.pod @@ -89,8 +89,7 @@ section containing configuration module specific information. E.g. ... engine stuff here ... -Currently there are two configuration modules. One for ASN1 objects another -for ENGINE configuration. +The features of each configuration module are described below. =head2 ASN1 OBJECT CONFIGURATION MODULE @@ -191,6 +190,25 @@ For example: # Supply all default algorithms default_algorithms = ALL +=head2 EVP CONFIGURATION MODULE + +This modules has the name B which points to a section containing +algorithm commands. + +Currently the only algorithm command supported is B whose +value should be a boolean string such as B or B. If the value is +B this attempt to enter FIPS mode. If the call fails or the library is +not FIPS capable then an error occurs. + +For example: + + alg_section = evp_settings + + [evp_settings] + + fips_mode = on + + =head1 NOTES If a configuration file attempts to expand a variable that doesn't exist diff --git a/doc/crypto/CONF_modules_load_file.pod b/doc/crypto/CONF_modules_load_file.pod index 0c4d926858..cc0b537b8e 100644 --- a/doc/crypto/CONF_modules_load_file.pod +++ b/doc/crypto/CONF_modules_load_file.pod @@ -9,9 +9,9 @@ #include int CONF_modules_load_file(const char *filename, const char *appname, - unsigned long flags); + unsigned long flags); int CONF_modules_load(const CONF *cnf, const char *appname, - unsigned long flags); + unsigned long flags); =head1 DESCRIPTION @@ -22,7 +22,7 @@ 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. +reads configuration information from B. =head1 NOTES @@ -30,7 +30,7 @@ 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. +considered fatal and no further modules are loaded. Normally any modules errors will add error information to the error queue. If B is set no error information is added. @@ -42,7 +42,84 @@ B if set will make CONF_load_modules_file() ignore missing configuration files. Normally a missing configuration file return an error. -=head1 RETURN VALUE +B if set and B is not NULL will use the +default section pointed to by B if B does not exist. + +Applications should call these functions after loading builtin modules using +OPENSSL_load_builtin_modules(), any ENGINEs for example using +ENGINE_load_builtin_engines(), any algorithms for example +OPENSSL_add_all_algorithms() and (if the application uses libssl) +SSL_library_init(). + +By using CONF_modules_load_file() with appropriate flags an application can +customise application configuration to best suit its needs. In some cases the +use of a configuration file is optional and its absence is not an error: in +this case B would be set. + +Errors during configuration may also be handled differently by different +applications. For example in some cases an error may simply print out a warning +message and the application continue. In other cases an application might +consider a configuration file error as fatal and exit immediately. + +Applications can use the CONF_modules_load() function if they wish to load a +configuration file themselves and have finer control over how errors are +treated. + +=head1 EXAMPLES + +Load a configuration file and print out any errors and exit (missing file +considered fatal): + + if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load default configuration file using the section indicated by "myapp", +tolerate missing files, but exit on other errors: + + if (CONF_modules_load_file(NULL, "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "FATAL: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + exit(1); + } + +Load custom configuration file and section, only print warnings on error, +missing configuration file ignored: + + if (CONF_modules_load_file("/something/app.cnf", "myapp", + CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { + fprintf(stderr, "WARNING: error loading configuration file\n"); + ERR_print_errors_fp(stderr); + } + +Load and parse configuration file manually, custom error handling: + + FILE *fp; + CONF *cnf = NULL; + long eline; + fp = fopen("/somepath/app.cnf", "r"); + if (fp == NULL) { + fprintf(stderr, "Error opening configuration file\n"); + /* Other missing configuration file behaviour */ + } else { + cnf = NCONF_new(NULL); + if (NCONF_load_fp(cnf, fp, &eline) == 0) { + fprintf(stderr, "Error on line %ld of configuration file\n", eline); + ERR_print_errors_fp(stderr); + /* Other malformed configuration file behaviour */ + } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { + fprintf(stderr, "Error configuring application\n"); + ERR_print_errors_fp(stderr); + /* Other configuration error behaviour */ + } + fclose(fp); + NCONF_free(cnf); + } + +=head1 RETURN VALUES 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