]>
Commit | Line | Data |
---|---|---|
aba3e65f DSH |
1 | |
2 | =pod | |
3 | ||
4 | =head1 NAME | |
5 | ||
19d2bb57 | 6 | config - OpenSSL CONF library configuration files |
aba3e65f DSH |
7 | |
8 | =head1 DESCRIPTION | |
9 | ||
19d2bb57 | 10 | The OpenSSL CONF library can be used to read configuration files. |
aba3e65f DSH |
11 | It is used for the OpenSSL master configuration file B<openssl.cnf> |
12 | and in a few other places like B<SPKAC> files and certificate extension | |
13 | files for the B<x509> utility. | |
14 | ||
15 | A configuration file is divided into a number of sections. Each section | |
16 | starts with a line B<[ section_name ]> and ends when a new section is | |
17 | started or end of file is reached. A section name can consist of | |
18 | alphanumeric characters and underscores. | |
19 | ||
20 | The first section of a configuration file is special and is referred | |
21 | to as the B<default> section this is usually unnamed and is from the | |
22 | start of file until the first named section. When a name is being looked up | |
23 | it is first looked up in a named section (if any) and then the | |
24 | default section. | |
25 | ||
26 | The environment is mapped onto a section called B<ENV>. | |
27 | ||
28 | Comments can be included by preceding them with the B<#> character | |
29 | ||
30 | Each section in a configuration file consists of a number of name and | |
31 | value pairs of the form B<name=value> | |
32 | ||
33 | The B<name> string can contain any alphanumeric characters as well as | |
34 | a few punctuation symbols such as B<.> B<,> B<;> and B<_>. | |
35 | ||
36 | The B<value> string consists of the string following the B<=> character | |
37 | until end of line with any leading and trailing white space removed. | |
38 | ||
39 | The value string undergoes variable expansion. This can be done by | |
40 | including the form B<$var> or B<${var}>: this will substitute the value | |
41 | of the named variable in the current section. It is also possible to | |
42 | substitute a value from another section using the syntax B<$section::name> | |
19d2bb57 | 43 | or B<${section::name}>. By using the form B<$ENV::name> environment |
aba3e65f DSH |
44 | variables can be substituted. It is also possible to assign values to |
45 | environment variables by using the name B<ENV::name>, this will work | |
46 | if the program looks up environment variables using the B<CONF> library | |
47 | instead of calling B<getenv()> directly. | |
48 | ||
49 | It is possible to escape certain characters by using any kind of quote | |
50 | or the B<\> character. By making the last character of a line a B<\> | |
51 | a B<value> string can be spread across multiple lines. In addition | |
52 | the sequences B<\n>, B<\r>, B<\b> and B<\t> are recognised. | |
53 | ||
54 | =head1 NOTES | |
55 | ||
19d2bb57 | 56 | If a configuration file attempts to expand a variable that doesn't exist |
aba3e65f DSH |
57 | then an error is flagged and the file will not load. This can happen |
58 | if an attempt is made to expand an environment variable that doesn't | |
59 | exist. For example the default OpenSSL master configuration file used | |
60 | the value of B<HOME> which may not be defined on non Unix systems. | |
61 | ||
62 | This can be worked around by including a B<default> section to provide | |
63 | a default value: then if the environment lookup fails the default value | |
64 | will be used instead. For this to work properly the default value must | |
65 | be defined earlier in the configuration file than the expansion. See | |
66 | the B<EXAMPLES> section for an example of how to do this. | |
67 | ||
68 | If the same variable exists in the same section then all but the last | |
69 | value will be silently ignored. In certain circumstances such as with | |
70 | DNs the same field may occur multiple times. This is usually worked | |
71 | around by ignoring any characters before an initial B<.> e.g. | |
72 | ||
73 | 1.OU="My first OU" | |
74 | 2.OU="My Second OU" | |
75 | ||
76 | =head1 EXAMPLES | |
77 | ||
78 | Here is a sample configuration file using some of the features | |
79 | mentioned above. | |
80 | ||
81 | # This is the default section. | |
82 | ||
83 | HOME=/temp | |
84 | RANDFILE= ${ENV::HOME}/.rnd | |
85 | configdir=$ENV::HOME/config | |
86 | ||
87 | [ section_one ] | |
88 | ||
89 | # We are now in section one. | |
90 | ||
91 | # Quotes permit leading and trailing whitespace | |
92 | any = " any variable name " | |
93 | ||
94 | other = A string that can \ | |
95 | cover several lines \ | |
96 | by including \\ characters | |
97 | ||
98 | message = Hello World\n | |
99 | ||
100 | [ section_two ] | |
101 | ||
102 | greeting = $section_one::message | |
103 | ||
104 | This next example shows how to expand environment variables safely. | |
105 | ||
106 | Suppose you want a variable called B<tmpfile> to refer to a | |
107 | temporary filename. The directory it is placed in can determined by | |
108 | the the B<TEMP> or B<TMP> environment variables but they may not be | |
109 | set to any value at all. If you just include the environment variable | |
110 | names and the variable doesn't exist then this will cause an error when | |
111 | an attempt is made to load the configuration file. By making use of the | |
112 | default section both values can be looked up with B<TEMP> taking | |
113 | priority and B</tmp> used if neither is defined: | |
114 | ||
115 | TMP=/tmp | |
116 | # The above value is used if TMP isn't in the environment | |
117 | TEMP=$ENV::TMP | |
118 | # The above value is used if TEMP isn't in the environment | |
119 | tmpfile=${ENV::TEMP}/tmp.filename | |
120 | ||
121 | =head1 BUGS | |
122 | ||
123 | Currently there is no way to include characters using the octal B<\nnn> | |
124 | form. Strings are all null terminated so nulls cannot form part of | |
125 | the value. | |
126 | ||
127 | The escaping isn't quite right: if you want to use sequences like B<\n> | |
128 | you can't use any quote escaping on the same line. | |
129 | ||
130 | Files are loaded in a single pass. This means that an variable expansion | |
131 | will only work if the variables referenced are defined earlier in the | |
132 | file. | |
133 | ||
134 | =head1 SEE ALSO | |
135 | ||
bb075f88 | 136 | L<x509(1)|x509(1)>, L<req(1)|req(1)>, L<ca(1)|ca(1)> |
aba3e65f DSH |
137 | |
138 | =cut |