- update OpenSSL to 0.9.8
[dragonfly.git] / secure / usr.bin / openssl / man / config.5
similarity index 55%
rename from secure/usr.bin/openssl/man/config.1
rename to secure/usr.bin/openssl/man/config.5
index b6d8584..d346174 100644 (file)
@@ -1,8 +1,7 @@
-.\" Automatically generated by Pod::Man version 1.15
-.\" Sun Jan 12 18:05:02 2003
+.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
 .\"
 .\" Standard preamble:
-.\" ======================================================================
+.\" ========================================================================
 .de Sh \" Subsection heading
 .br
 .if t .Sp
 .if t .sp .5v
 .if n .sp
 ..
-.de Ip \" List item
-.br
-.ie \\n(.$>=3 .ne \\$3
-.el .ne 3
-.IP "\\$1" \\$2
-..
 .de Vb \" Begin verbatim text
 .ft CW
 .nf
 ..
 .de Ve \" End verbatim text
 .ft R
-
 .fi
 ..
 .\" Set up some character translations and predefined strings.  \*(-- will
 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
 .\" double quote, and \*(R" will give a right double quote.  | will give a
-.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
-.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
-.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
+.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
+.\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
+.\" expand to `' in nroff, nothing in troff, for use with C<>.
 .tr \(*W-|\(bv\*(Tr
 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 .ie n \{\
 .    ds R" ''
 'br\}
 .\"
-.\" If the F register is turned on, we'll generate index entries on stderr
-.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
-.\" index entries marked with X<> in POD.  Of course, you'll have to process
-.\" the output yourself in some meaningful fashion.
+.\" If the F register is turned on, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" entries marked with X<> in POD.  Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
 .if \nF \{\
 .    de IX
 .    tm Index:\\$1\t\\n%\t"\\$2"
 .    rr F
 .\}
 .\"
-.\" For nroff, turn off justification.  Always turn off hyphenation; it
-.\" makes way too many mistakes in technical documents.
+.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
 .hy 0
 .if n .na
 .\"
 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
-.bd B 3
 .    \" fudge factors for nroff and troff
 .if n \{\
 .    ds #H 0
 .    ds Ae AE
 .\}
 .rm #[ #] #H #V #F C
-.\" ======================================================================
+.\" ========================================================================
 .\"
-.IX Title "config 3"
-.TH config 3 "0.9.7" "2003-01-12" "OpenSSL"
-.UC
+.IX Title "CONFIG 5"
+.TH CONFIG 5 "2005-07-06" "0.9.8" "OpenSSL"
 .SH "NAME"
-config \- OpenSSL \s-1CONF\s0 library configuration files
+config \- OpenSSL CONF library configuration files
 .SH "DESCRIPTION"
 .IX Header "DESCRIPTION"
 The OpenSSL \s-1CONF\s0 library can be used to read configuration files.
 It is used for the OpenSSL master configuration file \fBopenssl.cnf\fR
 and in a few other places like \fB\s-1SPKAC\s0\fR files and certificate extension
-files for the \fBx509\fR utility.
+files for the \fBx509\fR utility. OpenSSL applications can also use the
+\&\s-1CONF\s0 library for their own purposes.
 .PP
 A configuration file is divided into a number of sections. Each section
 starts with a line \fB[ section_name ]\fR and ends when a new section is
@@ -179,7 +170,7 @@ of the named variable in the current section. It is also possible to
 substitute a value from another section using the syntax \fB$section::name\fR
 or \fB${section::name}\fR. By using the form \fB$ENV::name\fR environment
 variables can be substituted. It is also possible to assign values to
-environment variables by using the name \fB\s-1ENV:\s0:name\fR, this will work
+environment variables by using the name \fBENV::name\fR, this will work
 if the program looks up environment variables using the \fB\s-1CONF\s0\fR library
 instead of calling \fB\f(BIgetenv()\fB\fR directly.
 .PP
@@ -187,13 +178,185 @@ It is possible to escape certain characters by using any kind of quote
 or the \fB\e\fR character. By making the last character of a line a \fB\e\fR
 a \fBvalue\fR string can be spread across multiple lines. In addition
 the sequences \fB\en\fR, \fB\er\fR, \fB\eb\fR and \fB\et\fR are recognized.
+.SH "OPENSSL LIBRARY CONFIGURATION"
+.IX Header "OPENSSL LIBRARY CONFIGURATION"
+In OpenSSL 0.9.7 and later applications can automatically configure certain
+aspects of OpenSSL using the master OpenSSL configuration file, or optionally
+an alternative configuration file. The \fBopenssl\fR utility includes this
+functionality: any sub command uses the master OpenSSL configuration file
+unless an option is used in the sub command to use an alternative configuration
+file.
+.PP
+To enable library configuration the default section needs to contain an 
+appropriate line which points to the main configuration section. The default
+name is \fBopenssl_conf\fR which is used by the \fBopenssl\fR utility. Other
+applications may use an alternative name such as \fBmyapplicaton_conf\fR.
+.PP
+The configuration section should consist of a set of name value pairs which
+contain specific module configuration information. The \fBname\fR represents
+the name of the \fIconfiguration module\fR the meaning of the \fBvalue\fR is 
+module specific: it may, for example, represent a further configuration
+section containing configuration module specific information. E.g.
+.PP
+.Vb 1
+\& openssl_conf = openssl_init
+.Ve
+.PP
+.Vb 1
+\& [openssl_init]
+.Ve
+.PP
+.Vb 2
+\& oid_section = new_oids
+\& engines = engine_section
+.Ve
+.PP
+.Vb 1
+\& [new_oids]
+.Ve
+.PP
+.Vb 1
+\& ... new oids here ...
+.Ve
+.PP
+.Vb 1
+\& [engine_section]
+.Ve
+.PP
+.Vb 1
+\& ... engine stuff here ...
+.Ve
+.PP
+Currently there are two configuration modules. One for \s-1ASN1\s0 objects another
+for \s-1ENGINE\s0 configuration.
+.Sh "\s-1ASN1\s0 \s-1OBJECT\s0 \s-1CONFIGURATION\s0 \s-1MODULE\s0"
+.IX Subsection "ASN1 OBJECT CONFIGURATION MODULE"
+This module has the name \fBoid_section\fR. The value of this variable points
+to a section containing name value pairs of OIDs: the name is the \s-1OID\s0 short
+and long name, the value is the numerical form of the \s-1OID\s0. Although some of
+the \fBopenssl\fR utility sub commands already have their own \s-1ASN1\s0 \s-1OBJECT\s0 section
+functionality not all do. By using the \s-1ASN1\s0 \s-1OBJECT\s0 configuration module
+\&\fBall\fR the \fBopenssl\fR utility sub commands can see the new objects as well
+as any compliant applications. For example:
+.PP
+.Vb 1
+\& [new_oids]
+.Ve
+.PP
+.Vb 2
+\& some_new_oid = 1.2.3.4
+\& some_other_oid = 1.2.3.5
+.Ve
+.PP
+In OpenSSL 0.9.8 it is also possible to set the value to the long name followed
+by a comma and the numerical \s-1OID\s0 form. For example:
+.PP
+.Vb 1
+\& shortName = some object long name, 1.2.3.4
+.Ve
+.Sh "\s-1ENGINE\s0 \s-1CONFIGURATION\s0 \s-1MODULE\s0"
+.IX Subsection "ENGINE CONFIGURATION MODULE"
+This \s-1ENGINE\s0 configuration module has the name \fBengines\fR. The value of this
+variable points to a section containing further \s-1ENGINE\s0 configuration
+information.
+.PP
+The section pointed to by \fBengines\fR is a table of engine names (though see
+\&\fBengine_id\fR below) and further sections containing configuration informations
+specific to each \s-1ENGINE\s0.
+.PP
+Each \s-1ENGINE\s0 specific section is used to set default algorithms, load
+dynamic, perform initialization and send ctrls. The actual operation performed
+depends on the \fIcommand\fR name which is the name of the name value pair. The
+currently supported commands are listed below.
+.PP
+For example:
+.PP
+.Vb 1
+\& [engine_section]
+.Ve
+.PP
+.Vb 4
+\& # Configure ENGINE named "foo"
+\& foo = foo_section
+\& # Configure ENGINE named "bar"
+\& bar = bar_section
+.Ve
+.PP
+.Vb 2
+\& [foo_section]
+\& ... foo ENGINE specific commands ...
+.Ve
+.PP
+.Vb 2
+\& [bar_section]
+\& ... "bar" ENGINE specific commands ...
+.Ve
+.PP
+The command \fBengine_id\fR is used to give the \s-1ENGINE\s0 name. If used this 
+command must be first. For example:
+.PP
+.Vb 3
+\& [engine_section]
+\& # This would normally handle an ENGINE named "foo"
+\& foo = foo_section
+.Ve
+.PP
+.Vb 3
+\& [foo_section]
+\& # Override default name and use "myfoo" instead.
+\& engine_id = myfoo
+.Ve
+.PP
+The command \fBdynamic_path\fR loads and adds an \s-1ENGINE\s0 from the given path. It
+is equivalent to sending the ctrls \fB\s-1SO_PATH\s0\fR with the path argument followed
+by \fB\s-1LIST_ADD\s0\fR with value 2 and \fB\s-1LOAD\s0\fR to the dynamic \s-1ENGINE\s0. If this is
+not the required behaviour then alternative ctrls can be sent directly
+to the dynamic \s-1ENGINE\s0 using ctrl commands.
+.PP
+The command \fBinit\fR determines whether to initialize the \s-1ENGINE\s0. If the value
+is \fB0\fR the \s-1ENGINE\s0 will not be initialized, if \fB1\fR and attempt it made to
+initialized the \s-1ENGINE\s0 immediately. If the \fBinit\fR command is not present
+then an attempt will be made to initialize the \s-1ENGINE\s0 after all commands in
+its section have been processed.
+.PP
+The command \fBdefault_algorithms\fR sets the default algorithms an \s-1ENGINE\s0 will
+supply using the functions \fB\f(BIENGINE_set_default_string()\fB\fR
+.PP
+If the name matches none of the above command names it is assumed to be a
+ctrl command which is sent to the \s-1ENGINE\s0. The value of the command is the 
+argument to the ctrl command. If the value is the string \fB\s-1EMPTY\s0\fR then no
+value is sent to the command.
+.PP
+For example:
+.PP
+.Vb 1
+\& [engine_section]
+.Ve
+.PP
+.Vb 2
+\& # Configure ENGINE named "foo"
+\& foo = foo_section
+.Ve
+.PP
+.Vb 9
+\& [foo_section]
+\& # Load engine from DSO
+\& dynamic_path = /some/path/fooengine.so
+\& # A foo specific ctrl.
+\& some_ctrl = some_value
+\& # Another ctrl that doesn't take a value.
+\& other_ctrl = EMPTY
+\& # Supply all default algorithms
+\& default_algorithms = ALL
+.Ve
 .SH "NOTES"
 .IX Header "NOTES"
 If a configuration file attempts to expand a variable that doesn't exist
 then an error is flagged and the file will not load. This can happen
 if an attempt is made to expand an environment variable that doesn't
-exist. For example the default OpenSSL master configuration file used
-the value of \fB\s-1HOME\s0\fR which may not be defined on non Unix systems.
+exist. For example in a previous version of OpenSSL the default OpenSSL
+master configuration file used the value of \fB\s-1HOME\s0\fR which may not be
+defined on non Unix systems and would cause an error.
 .PP
 This can be worked around by including a \fBdefault\fR section to provide
 a default value: then if the environment lookup fails the default value
@@ -218,35 +381,44 @@ mentioned above.
 .Vb 1
 \& # This is the default section.
 .Ve
+.PP
 .Vb 3
 \& HOME=/temp
 \& RANDFILE= ${ENV::HOME}/.rnd
 \& configdir=$ENV::HOME/config
 .Ve
+.PP
 .Vb 1
 \& [ section_one ]
 .Ve
+.PP
 .Vb 1
 \& # We are now in section one.
 .Ve
+.PP
 .Vb 2
 \& # Quotes permit leading and trailing whitespace
 \& any = " any variable name "
 .Ve
+.PP
 .Vb 3
 \& other = A string that can \e
 \& cover several lines \e
 \& by including \e\e characters
 .Ve
+.PP
 .Vb 1
 \& message = Hello World\en
 .Ve
+.PP
 .Vb 1
 \& [ section_two ]
 .Ve
+.PP
 .Vb 1
 \& greeting = $section_one::message
 .Ve
+.PP
 This next example shows how to expand environment variables safely.
 .PP
 Suppose you want a variable called \fBtmpfile\fR to refer to a
@@ -279,4 +451,4 @@ will only work if the variables referenced are defined earlier in the
 file.
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
-x509(1), req(1), ca(1)
+\&\fIx509\fR\|(1), \fIreq\fR\|(1), \fIca\fR\|(1)