1127128Snectar=pod 2127128Snectar 3127128Snectar=head1 NAME 4127128Snectar 5127128Snectar CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions 6127128Snectar 7127128Snectar=head1 SYNOPSIS 8127128Snectar 9127128Snectar #include <openssl/conf.h> 10127128Snectar 11127128Snectar int CONF_modules_load_file(const char *filename, const char *appname, 12280304Sjkim unsigned long flags); 13127128Snectar int CONF_modules_load(const CONF *cnf, const char *appname, 14280304Sjkim unsigned long flags); 15127128Snectar 16127128Snectar=head1 DESCRIPTION 17127128Snectar 18127128SnectarThe function CONF_modules_load_file() configures OpenSSL using file 19127128SnectarB<filename> and application name B<appname>. If B<filename> is NULL 20127128Snectarthe standard OpenSSL configuration file is used. If B<appname> is 21127128SnectarNULL the standard OpenSSL application name B<openssl_conf> is used. 22127128SnectarThe behaviour can be cutomized using B<flags>. 23127128Snectar 24127128SnectarCONF_modules_load() is idential to CONF_modules_load_file() except it 25280304Sjkimreads configuration information from B<cnf>. 26127128Snectar 27127128Snectar=head1 NOTES 28127128Snectar 29127128SnectarThe following B<flags> are currently recognized: 30127128Snectar 31127128SnectarB<CONF_MFLAGS_IGNORE_ERRORS> if set errors returned by individual 32127128Snectarconfiguration modules are ignored. If not set the first module error is 33280304Sjkimconsidered fatal and no further modules are loaded. 34127128Snectar 35127128SnectarNormally any modules errors will add error information to the error queue. If 36127128SnectarB<CONF_MFLAGS_SILENT> is set no error information is added. 37127128Snectar 38127128SnectarIf B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is 39127128Snectardisabled. 40127128Snectar 41127128SnectarB<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file() 42127128Snectarignore missing configuration files. Normally a missing configuration file 43127128Snectarreturn an error. 44127128Snectar 45280304SjkimB<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the 46280304Sjkimdefault section pointed to by B<openssl_conf> if B<appname> does not exist. 47127128Snectar 48280304SjkimApplications should call these functions after loading builtin modules using 49280304SjkimOPENSSL_load_builtin_modules(), any ENGINEs for example using 50280304SjkimENGINE_load_builtin_engines(), any algorithms for example 51280304SjkimOPENSSL_add_all_algorithms() and (if the application uses libssl) 52280304SjkimSSL_library_init(). 53280304Sjkim 54280304SjkimBy using CONF_modules_load_file() with appropriate flags an application can 55280304Sjkimcustomise application configuration to best suit its needs. In some cases the 56280304Sjkimuse of a configuration file is optional and its absence is not an error: in 57280304Sjkimthis case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set. 58280304Sjkim 59280304SjkimErrors during configuration may also be handled differently by different 60280304Sjkimapplications. For example in some cases an error may simply print out a warning 61280304Sjkimmessage and the application continue. In other cases an application might 62280304Sjkimconsider a configuration file error as fatal and exit immediately. 63280304Sjkim 64280304SjkimApplications can use the CONF_modules_load() function if they wish to load a 65280304Sjkimconfiguration file themselves and have finer control over how errors are 66280304Sjkimtreated. 67280304Sjkim 68280304Sjkim=head1 EXAMPLES 69280304Sjkim 70280304SjkimLoad a configuration file and print out any errors and exit (missing file 71280304Sjkimconsidered fatal): 72280304Sjkim 73280304Sjkim if (CONF_modules_load_file(NULL, NULL, 0) <= 0) { 74280304Sjkim fprintf(stderr, "FATAL: error loading configuration file\n"); 75280304Sjkim ERR_print_errors_fp(stderr); 76280304Sjkim exit(1); 77280304Sjkim } 78280304Sjkim 79280304SjkimLoad default configuration file using the section indicated by "myapp", 80280304Sjkimtolerate missing files, but exit on other errors: 81280304Sjkim 82280304Sjkim if (CONF_modules_load_file(NULL, "myapp", 83280304Sjkim CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { 84280304Sjkim fprintf(stderr, "FATAL: error loading configuration file\n"); 85280304Sjkim ERR_print_errors_fp(stderr); 86280304Sjkim exit(1); 87280304Sjkim } 88280304Sjkim 89280304SjkimLoad custom configuration file and section, only print warnings on error, 90280304Sjkimmissing configuration file ignored: 91280304Sjkim 92280304Sjkim if (CONF_modules_load_file("/something/app.cnf", "myapp", 93280304Sjkim CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) { 94280304Sjkim fprintf(stderr, "WARNING: error loading configuration file\n"); 95280304Sjkim ERR_print_errors_fp(stderr); 96280304Sjkim } 97280304Sjkim 98280304SjkimLoad and parse configuration file manually, custom error handling: 99280304Sjkim 100280304Sjkim FILE *fp; 101280304Sjkim CONF *cnf = NULL; 102280304Sjkim long eline; 103280304Sjkim fp = fopen("/somepath/app.cnf", "r"); 104280304Sjkim if (fp == NULL) { 105280304Sjkim fprintf(stderr, "Error opening configuration file\n"); 106280304Sjkim /* Other missing configuration file behaviour */ 107280304Sjkim } else { 108280304Sjkim cnf = NCONF_new(NULL); 109280304Sjkim if (NCONF_load_fp(cnf, fp, &eline) == 0) { 110280304Sjkim fprintf(stderr, "Error on line %ld of configuration file\n", eline); 111280304Sjkim ERR_print_errors_fp(stderr); 112280304Sjkim /* Other malformed configuration file behaviour */ 113280304Sjkim } else if (CONF_modules_load(cnf, "appname", 0) <= 0) { 114280304Sjkim fprintf(stderr, "Error configuring application\n"); 115280304Sjkim ERR_print_errors_fp(stderr); 116280304Sjkim /* Other configuration error behaviour */ 117280304Sjkim } 118280304Sjkim fclose(fp); 119280304Sjkim NCONF_free(cnf); 120280304Sjkim } 121280304Sjkim 122280304Sjkim=head1 RETURN VALUES 123280304Sjkim 124127128SnectarThese functions return 1 for success and a zero or negative value for 125127128Snectarfailure. If module errors are not ignored the return code will reflect the 126127128Snectarreturn value of the failing module (this will always be zero or negative). 127127128Snectar 128127128Snectar=head1 SEE ALSO 129127128Snectar 130127128SnectarL<conf(5)|conf(5)>, L<OPENSSL_config(3)|OPENSSL_config(3)>, 131267258SjkimL<CONF_free(3)|CONF_free(3)>, L<err(3)|err(3)> 132127128Snectar 133127128Snectar=head1 HISTORY 134127128Snectar 135127128SnectarCONF_modules_load_file and CONF_modules_load first appeared in OpenSSL 0.9.7. 136127128Snectar 137127128Snectar=cut 138