211eca06fac8b0bd9578aadf358163008c602222
[openssl.git] / doc / man3 / CONF_modules_load_file.pod
1 =pod
2
3 =head1 NAME
4
5 CONF_modules_load_file, CONF_modules_load - OpenSSL configuration functions
6
7 =head1 SYNOPSIS
8
9  #include <openssl/conf.h>
10
11  int CONF_modules_load_file(const char *filename, const char *appname,
12                             unsigned long flags);
13  int CONF_modules_load(const CONF *cnf, const char *appname,
14                        unsigned long flags);
15
16 =head1 DESCRIPTION
17
18 The function CONF_modules_load_file() configures OpenSSL using file
19 B<filename> and application name B<appname>. If B<filename> is NULL
20 the standard OpenSSL configuration file is used. If B<appname> is
21 NULL the standard OpenSSL application name B<openssl_conf> is used.
22 The behaviour can be customized using B<flags>.
23
24 CONF_modules_load() is identical to CONF_modules_load_file() except it
25 reads configuration information from B<cnf>.
26
27 =head1 NOTES
28
29 The following B<flags> are currently recognized:
30
31 If B<CONF_MFLAGS_IGNORE_ERRORS> is set errors returned by individual
32 configuration modules are ignored. If not set the first module error is
33 considered fatal and no further modules are loaded.
34
35 Normally any modules errors will add error information to the error queue. If
36 B<CONF_MFLAGS_SILENT> is set no error information is added.
37
38 If B<CONF_MFLAGS_IGNORE_RETURN_CODES> is set the function unconditionally
39 returns success.
40 This is used by default in L<OPENSSL_init_crypto(3)> to ignore any errors in
41 the default system-wide configuration file, as having all OpenSSL applications
42 fail to start when there are potentially minor issues in the file is too risky.
43 Applications calling B<CONF_modules_load_file> explicitly should not generally
44 set this flag.
45
46 If B<CONF_MFLAGS_NO_DSO> is set configuration module loading from DSOs is
47 disabled.
48
49 B<CONF_MFLAGS_IGNORE_MISSING_FILE> if set will make CONF_load_modules_file()
50 ignore missing configuration files. Normally a missing configuration file
51 return an error.
52
53 B<CONF_MFLAGS_DEFAULT_SECTION> if set and B<appname> is not NULL will use the
54 default section pointed to by B<openssl_conf> if B<appname> does not exist.
55
56 By using CONF_modules_load_file() with appropriate flags an application can
57 customise application configuration to best suit its needs. In some cases the
58 use of a configuration file is optional and its absence is not an error: in
59 this case B<CONF_MFLAGS_IGNORE_MISSING_FILE> would be set.
60
61 Errors during configuration may also be handled differently by different
62 applications. For example in some cases an error may simply print out a warning
63 message and the application continue. In other cases an application might
64 consider a configuration file error as fatal and exit immediately.
65
66 Applications can use the CONF_modules_load() function if they wish to load a
67 configuration file themselves and have finer control over how errors are
68 treated.
69
70 =head1 EXAMPLES
71
72 Load a configuration file and print out any errors and exit (missing file
73 considered fatal):
74
75  if (CONF_modules_load_file(NULL, NULL, 0) <= 0) {
76      fprintf(stderr, "FATAL: error loading configuration file\n");
77      ERR_print_errors_fp(stderr);
78      exit(1);
79  }
80
81 Load default configuration file using the section indicated by "myapp",
82 tolerate missing files, but exit on other errors:
83
84  if (CONF_modules_load_file(NULL, "myapp",
85                             CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
86      fprintf(stderr, "FATAL: error loading configuration file\n");
87      ERR_print_errors_fp(stderr);
88      exit(1);
89  }
90
91 Load custom configuration file and section, only print warnings on error,
92 missing configuration file ignored:
93
94  if (CONF_modules_load_file("/something/app.cnf", "myapp",
95                             CONF_MFLAGS_IGNORE_MISSING_FILE) <= 0) {
96      fprintf(stderr, "WARNING: error loading configuration file\n");
97      ERR_print_errors_fp(stderr);
98  }
99
100 Load and parse configuration file manually, custom error handling:
101
102  FILE *fp;
103  CONF *cnf = NULL;
104  long eline;
105
106  fp = fopen("/somepath/app.cnf", "r");
107  if (fp == NULL) {
108      fprintf(stderr, "Error opening configuration file\n");
109      /* Other missing configuration file behaviour */
110  } else {
111      cnf = NCONF_new(NULL);
112      if (NCONF_load_fp(cnf, fp, &eline) == 0) {
113          fprintf(stderr, "Error on line %ld of configuration file\n", eline);
114          ERR_print_errors_fp(stderr);
115          /* Other malformed configuration file behaviour */
116      } else if (CONF_modules_load(cnf, "appname", 0) <= 0) {
117          fprintf(stderr, "Error configuring application\n");
118          ERR_print_errors_fp(stderr);
119          /* Other configuration error behaviour */
120      }
121      fclose(fp);
122      NCONF_free(cnf);
123  }
124
125 =head1 RETURN VALUES
126
127 These functions return 1 for success and a zero or negative value for
128 failure. If module errors are not ignored the return code will reflect the
129 return value of the failing module (this will always be zero or negative).
130
131 =head1 SEE ALSO
132
133 L<config(5)>, L<OPENSSL_config(3)>
134
135 =head1 COPYRIGHT
136
137 Copyright 2004-2017 The OpenSSL Project Authors. All Rights Reserved.
138
139 Licensed under the OpenSSL license (the "License").  You may not use
140 this file except in compliance with the License.  You can obtain a copy
141 in the file LICENSE in the source distribution or at
142 L<https://www.openssl.org/source/license.html>.
143
144 =cut