summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/openssl.cnf.5
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/man/openssl.cnf.5')
-rw-r--r--src/lib/libcrypto/man/openssl.cnf.5361
1 files changed, 0 insertions, 361 deletions
diff --git a/src/lib/libcrypto/man/openssl.cnf.5 b/src/lib/libcrypto/man/openssl.cnf.5
deleted file mode 100644
index 4047eb059a..0000000000
--- a/src/lib/libcrypto/man/openssl.cnf.5
+++ /dev/null
@@ -1,361 +0,0 @@
1.\" $OpenBSD: openssl.cnf.5,v 1.11 2024/07/08 15:02:28 jmc Exp $
2.\" full merge up to: OpenSSL man5/config b53338cb Feb 28 12:30:28 2017 +0100
3.\" selective merge up to: OpenSSL a8c5ed81 Jul 18 13:57:25 2017 -0400
4.\"
5.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
6.\" Copyright (c) 1999, 2000, 2004, 2013, 2015, 2016, 2017 The OpenSSL Project.
7.\" All rights reserved.
8.\"
9.\" Redistribution and use in source and binary forms, with or without
10.\" modification, are permitted provided that the following conditions
11.\" are met:
12.\"
13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer.
15.\"
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\" notice, this list of conditions and the following disclaimer in
18.\" the documentation and/or other materials provided with the
19.\" distribution.
20.\"
21.\" 3. All advertising materials mentioning features or use of this
22.\" software must display the following acknowledgment:
23.\" "This product includes software developed by the OpenSSL Project
24.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
25.\"
26.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
27.\" endorse or promote products derived from this software without
28.\" prior written permission. For written permission, please contact
29.\" openssl-core@openssl.org.
30.\"
31.\" 5. Products derived from this software may not be called "OpenSSL"
32.\" nor may "OpenSSL" appear in their names without prior written
33.\" permission of the OpenSSL Project.
34.\"
35.\" 6. Redistributions of any form whatsoever must retain the following
36.\" acknowledgment:
37.\" "This product includes software developed by the OpenSSL Project
38.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
39.\"
40.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
41.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
42.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
43.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
44.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
45.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
46.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
47.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
48.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
49.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
50.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
51.\" OF THE POSSIBILITY OF SUCH DAMAGE.
52.\"
53.Dd $Mdocdate: July 8 2024 $
54.Dt OPENSSL.CNF 5
55.Os
56.Sh NAME
57.Nm openssl.cnf
58.Nd OpenSSL configuration files
59.Sh DESCRIPTION
60The OpenSSL CONF library can be used to read configuration files; see
61.Xr CONF_modules_load_file 3 .
62It is used for the OpenSSL master configuration file
63.Pa /etc/ssl/openssl.cnf
64and in a few other places such as certificate extension files for the
65.Xr openssl 1
66.Cm x509
67utility.
68OpenSSL applications can also use the CONF library for their own
69purposes.
70.Pp
71A configuration file is divided into a number of sections.
72Each section starts with a line
73.Bq Ar section_name
74and ends when a new section is started or the end of the file is reached.
75A section name can consist of alphanumeric characters and underscores.
76.Pp
77The first section of a configuration file is special and is referred to
78as the
79.Dq default section .
80It is usually unnamed and extends from the start of file to the
81first named section.
82When a name is being looked up, it is first looked up in a named
83section (if any) and then in the default section.
84.Pp
85The environment is mapped onto a section called
86.Ic ENV .
87.Pp
88Comments can be included by preceding them with the
89.Ql #
90character.
91.Pp
92Each section in a configuration file consists of a number of name and
93value pairs of the form
94.Ar name Ns = Ns Ar value .
95.Pp
96The
97.Ar name
98string can contain any alphanumeric characters as well as a few
99punctuation symbols such as
100.Ql \&.
101.Ql \&,
102.Ql \&;
103and
104.Ql _ .
105.Pp
106The
107.Ar value
108string consists of the string following the
109.Ql =
110character until the end of the line with any leading and trailing
111whitespace removed.
112.Pp
113The value string undergoes variable expansion.
114This can be done by including substrings of the form
115.Pf $ Ar name
116or
117.Pf $ Brq Ar name :
118this will substitute the value of the named variable in the current
119section.
120It is also possible to substitute a value from another section using the
121syntax
122.Pf $ Ar section Ns :: Ns Ar name
123or
124.Pf $ Brq Ar section Ns :: Ns Ar name .
125By using the form
126.Pf $ Ic ENV Ns :: Ns Ar name ,
127environment variables can be substituted.
128It is also possible to assign values to environment variables by using
129the name
130.Ic ENV Ns :: Ns Ar name .
131This will work if the program looks up environment variables using
132the CONF library instead of calling
133.Xr getenv 3
134directly.
135The value string must not exceed 64k in length after variable expansion or an
136error will occur.
137.Pp
138It is possible to escape certain characters by using any kind of quote
139or the
140.Ql \e
141character.
142By making the last character of a line a
143.Ql \e ,
144a
145.Ar value
146string can be spread across multiple lines.
147In addition the sequences
148.Ql \en ,
149.Ql \er ,
150.Ql \eb ,
151and
152.Ql \et
153are recognized.
154.Sh OPENSSL LIBRARY CONFIGURATION
155Applications can automatically configure certain aspects of OpenSSL
156using the master OpenSSL configuration file, or optionally an
157alternative configuration file.
158The
159.Xr openssl 1
160utility includes this functionality: any sub command uses the master
161OpenSSL configuration file unless an option is used in the sub command
162to use an alternative configuration file.
163.Pp
164To enable library configuration, the default section needs to contain
165an appropriate line which points to the main configuration section.
166The default name is
167.Ic openssl_conf ,
168which is used by the
169.Xr openssl 1
170utility.
171Other applications may use an alternative name such as
172.Sy myapplication_conf .
173All library configuration lines appear in the default section
174at the start of the configuration file.
175.Pp
176The configuration section should consist of a set of name value pairs
177which contain specific module configuration information.
178The
179.Ar name
180represents the name of the configuration module.
181The meaning of the
182.Ar value
183is module specific: it may, for example, represent a further
184configuration section containing configuration module specific
185information.
186For example:
187.Bd -literal -offset indent
188# The following line must be in the default section.
189openssl_conf = openssl_init
190
191[openssl_init]
192oid_section = new_oids
193
194[new_oids]
195\&... new oids here ...
196.Ed
197.Pp
198The features of each configuration module are described below.
199.Ss ASN1 Object Configuration Module
200This module has the name
201.Ic oid_section .
202The value of this variable points to a section containing name value
203pairs of OIDs: the name is the OID short and long name, and the value is the
204numerical form of the OID.
205Although some of the
206.Xr openssl 1
207utility subcommands already have their own ASN1 OBJECT section
208functionality, not all do.
209By using the ASN1 OBJECT configuration module, all the
210.Xr openssl 1
211utility subcommands can see the new objects as well as any compliant
212applications.
213For example:
214.Bd -literal -offset indent
215[new_oids]
216some_new_oid = 1.2.3.4
217some_other_oid = 1.2.3.5
218.Ed
219.Pp
220It is also possible to set the value to the long name followed by a
221comma and the numerical OID form.
222For example:
223.Pp
224.Dl shortName = some object long name, 1.2.3.4
225.Sh FILES
226.Bl -tag -width /etc/ssl/openssl.cnf -compact
227.It Pa /etc/ssl/openssl.cnf
228standard configuration file
229.El
230.Sh EXAMPLES
231Here is a sample configuration file using some of the features
232mentioned above:
233.Bd -literal -offset indent
234# This is the default section.
235HOME=/temp
236RANDFILE= ${ENV::HOME}/.rnd
237configdir=$ENV::HOME/config
238
239[ section_one ]
240# We are now in section one.
241
242# Quotes permit leading and trailing whitespace
243any = " any variable name "
244
245other = A string that can \e
246cover several lines \e
247by including \e\e characters
248
249message = Hello World\en
250
251[ section_two ]
252greeting = $section_one::message
253.Ed
254.Pp
255This next example shows how to expand environment variables safely.
256.Pp
257Suppose you want a variable called
258.Sy tmpfile
259to refer to a temporary filename.
260The directory it is placed in can determined by the
261.Ev TEMP
262or
263.Ev TMP
264environment variables but they may not be set to any value at all.
265If you just include the environment variable names and the variable
266doesn't exist then this will cause an error when an attempt is made to
267load the configuration file.
268By making use of the default section both values can be looked up with
269.Ev TEMP
270taking priority and
271.Pa /tmp
272used if neither is defined:
273.Bd -literal -offset indent
274TMP=/tmp
275# The above value is used if TMP isn't in the environment
276TEMP=$ENV::TMP
277# The above value is used if TEMP isn't in the environment
278tmpfile=${ENV::TEMP}/tmp.filename
279.Ed
280.Pp
281More complex OpenSSL library configuration.
282Add OID:
283.Bd -literal -offset indent
284# Default appname: should match "appname" parameter (if any)
285# supplied to CONF_modules_load_file et al.
286openssl_conf = openssl_conf_section
287
288[openssl_conf_section]
289# Configuration module list
290oid_section = new_oids
291
292[new_oids]
293# New OID, just short name
294newoid1 = 1.2.3.4.1
295# New OID shortname and long name
296newoid2 = New OID 2 long name, 1.2.3.4.2
297.Ed
298.Pp
299The above examples can be used with any application supporting library
300configuration if "openssl_conf" is modified to match the appropriate
301"appname".
302.Pp
303For example if the second sample file above is saved to "example.cnf"
304then the command line:
305.Pp
306.Dl OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
307.Pp
308will output:
309.Dl 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
310.Pp
311showing that the OID "newoid1" has been added as "1.2.3.4.1".
312.Sh SEE ALSO
313.Xr openssl 1 ,
314.Xr CONF_modules_load_file 3 ,
315.Xr OPENSSL_config 3 ,
316.Xr x509v3.cnf 5
317.Sh CAVEATS
318If a configuration file attempts to expand a variable that doesn't
319exist, then an error is flagged and the file will not load.
320This can also happen if an attempt is made to expand an environment
321variable that doesn't exist.
322For example, in a previous version of OpenSSL the default OpenSSL
323master configuration file used the value of
324.Ev HOME
325which may not be defined on non Unix systems and would cause an error.
326.Pp
327This can be worked around by including a default section to provide
328a default value: then if the environment lookup fails, the default
329value will be used instead.
330For this to work properly, the default value must be defined earlier
331in the configuration file than the expansion.
332See the
333.Sx EXAMPLES
334section for an example of how to do this.
335.Pp
336If the same variable is defined more than once in the same section,
337then all but the last value will be silently ignored.
338In certain circumstances such as with DNs, the same field may occur
339multiple times.
340This is usually worked around by ignoring any characters before an
341initial
342.Ql \&. ,
343for example:
344.Bd -literal -offset indent
3451.OU="My first OU"
3462.OU="My Second OU"
347.Ed
348.Sh BUGS
349Currently there is no way to include characters using the octal
350.Pf \e Ar nnn
351form.
352Strings are all NUL terminated, so NUL bytes cannot form part of
353the value.
354.Pp
355The escaping isn't quite right: if you want to use sequences like
356.Ql \en ,
357you can't use any quote escaping on the same line.
358.Pp
359Files are loaded in a single pass.
360This means that a variable expansion will only work if the variables
361referenced are defined earlier in the file.