import openssl.cnf(5) and x509v3.cnf(5) from OpenSSL;

below OpenBSD quality standards, but better than nothing...

6 files changed, 1259 insertions, 14 deletions

diff --git a/src/lib/libcrypto/man/ASN1_generate_nconf.3 b/src/lib/libcrypto/man/ASN1_generate_nconf.3
index 2d5d8c7a73..bcf55d724b 100644
--- a/src/lib/libcrypto/man/ASN1_generate_nconf.3
+++ b/src/lib/libcrypto/man/ASN1_generate_nconf.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_generate_nconf.3,v 1.7 2016/11/10 13:06:24 schwarze Exp $
+.\"     $OpenBSD: ASN1_generate_nconf.3,v 1.8 2016/12/11 18:06:09 schwarze Exp $
 .\"     OpenSSL 05ea606a Fri May 20 20:52:46 2016 -0400
 .\"
 .\" This file was written by Dr. Stephen Henson.
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 10 2016 $
+.Dd $Mdocdate: December 11 2016 $
 .Dt ASN1_GENERATE_NCONF 3
 .Os
 .Sh NAME
@@ -374,7 +374,8 @@ D4D2C6D000430DEC66ABF47829E74B8C5108623A1C0EE8BE217B3AD8D36D5EB4FCA1D9
 e=INTEGER:0x010001
 .Ed
 .Sh SEE ALSO
-.Xr ERR_get_error 3
+.Xr ERR_get_error 3 ,
+.Xr x509v3.cnf 5
 .Sh HISTORY
 .Fn ASN1_generate_nconf
 and
diff --git a/src/lib/libcrypto/man/CONF_modules_load_file.3 b/src/lib/libcrypto/man/CONF_modules_load_file.3
index 0e594a1544..620787b4f1 100644
--- a/src/lib/libcrypto/man/CONF_modules_load_file.3
+++ b/src/lib/libcrypto/man/CONF_modules_load_file.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: CONF_modules_load_file.3,v 1.4 2016/11/20 19:47:59 schwarze Exp $
+.\"     $OpenBSD: CONF_modules_load_file.3,v 1.5 2016/12/11 18:06:09 schwarze Exp $
 .\"     OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 20 2016 $
+.Dd $Mdocdate: December 11 2016 $
 .Dt CONF_MODULES_LOAD_FILE 3
 .Os
 .Sh NAME
@@ -72,15 +72,19 @@
 .Sh DESCRIPTION
 The function
 .Fn CONF_modules_load_file
-configures OpenSSL using file
+configures OpenSSL using the file
 .Fa filename
-and application name
+in
+.Xr openssl.cnf 5
+format and the application name
 .Fa appname .
 If
 .Fa filename
 is
 .Dv NULL ,
-the standard OpenSSL configuration file is used.
+the standard OpenSSL configuration file
+.Pa /etc/ssl/openssl.cnf
+is used.
 If
 .Fa appname
 is
@@ -149,6 +153,11 @@ These functions return 1 for success and zero or a negative value for
 failure.
 If module errors are not ignored, the return code will reflect the return
 value of the failing module (this will always be zero or negative).
+.Sh FILES
+.Bl -tag -width /etc/ssl/openssl.cnf -compact
+.It Pa /etc/ssl/openssl.cnf
+standard configuration file
+.El
 .Sh EXAMPLES
 Load a configuration file and print out any errors and exit (missing
 file considered fatal):
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index 4d23082d1f..89533851fb 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.73 2016/12/11 14:22:43 schwarze Exp $
+# $OpenBSD: Makefile,v 1.74 2016/12/11 18:06:09 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -218,7 +218,9 @@ MAN=	\
         i2d_PKCS7_bio_stream.3 \
         lh_new.3 \
         lh_stats.3 \
-        x509.3
+        x509.3 \
+        openssl.cnf.5 \
+        x509v3.cnf.5
 
 all clean cleandir depend includes obj tags:
 
diff --git a/src/lib/libcrypto/man/OPENSSL_config.3 b/src/lib/libcrypto/man/OPENSSL_config.3
index e6968171c4..bf42b72fd2 100644
--- a/src/lib/libcrypto/man/OPENSSL_config.3
+++ b/src/lib/libcrypto/man/OPENSSL_config.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: OPENSSL_config.3,v 1.4 2016/11/28 14:52:20 schwarze Exp $
+.\"     $OpenBSD: OPENSSL_config.3,v 1.5 2016/12/11 18:06:09 schwarze Exp $
 .\"     OpenSSL ab6577a4 May 14 21:07:51 2014 +0100
 .\"
 .\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
@@ -48,7 +48,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: November 28 2016 $
+.Dd $Mdocdate: December 11 2016 $
 .Dt OPENSSL_CONFIG 3
 .Os
 .Sh NAME
@@ -66,7 +66,7 @@
 .Sh DESCRIPTION
 .Fn OPENSSL_config
 configures OpenSSL using the standard
-.Pa openssl.cnf
+.Xr openssl.cnf 5
 configuration file name using
 .Fa config_name .
 If
@@ -139,9 +139,15 @@ Neither
 nor
 .Fn OPENSSL_no_config
 return a value.
+.Sh FILES
+.Bl -tag -width /etc/ssl/openssl.cnf -compact
+.It Pa /etc/ssl/openssl.cnf
+standard configuration file
+.El
 .Sh SEE ALSO
 .Xr CONF_modules_free 3 ,
-.Xr CONF_modules_load 3
+.Xr CONF_modules_load 3 ,
+.Xr openssl.cnf 5
 .Sh HISTORY
 .Fn OPENSSL_config
 and
diff --git a/src/lib/libcrypto/man/openssl.cnf.5 b/src/lib/libcrypto/man/openssl.cnf.5
new file mode 100644
index 0000000000..2826b779ba
--- /dev/null
+++ b/src/lib/libcrypto/man/openssl.cnf.5
@@ -0,0 +1,496 @@
+.\"     $OpenBSD: openssl.cnf.5,v 1.1 2016/12/11 18:06:09 schwarze Exp $
+.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\"
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" Copyright (c) 1999, 2000, 2004, 2013, 2015, 2016 The OpenSSL Project.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 11 2016 $
+.Dt OPENSSL.CNF 5
+.Os
+.Sh NAME
+.Nm openssl.cnf
+.Nd OpenSSL configuration files
+.Sh DESCRIPTION
+The OpenSSL CONF library can be used to read configuration files, see
+.Xr CONF_modules_load_file 3 .
+It is used for the OpenSSL master configuration file
+.Pa /etc/ssl/openssl.cnf
+and in a few other places like
+.Sy SPKAC
+files and certificate extension files for the
+.Xr openssl 1
+.Cm x509
+utility.
+OpenSSL applications can also use the CONF library for their own
+purposes.
+.Pp
+A configuration file is divided into a number of sections.
+Each section starts with a line
+.Bq Ar section_name
+and ends when a new section is started or the end of the file is reached.
+A section name can consist of alphanumeric characters and underscores.
+.Pp
+The first section of a configuration file is special and is referred to
+as the
+.Dq default section .
+It is usually unnamed and extends from the start of file to the
+first named section.
+When a name is being looked up, it is first looked up in a named
+section (if any) and then in the default section.
+.Pp
+The environment is mapped onto a section called
+.Ic ENV .
+.Pp
+Comments can be included by preceding them with the
+.Ql #
+character.
+.Pp
+Each section in a configuration file consists of a number of name and
+value pairs of the form
+.Ar name Ns = Ns Ar value .
+.Pp
+The
+.Ar name
+string can contain any alphanumeric characters as well as a few
+punctuation symbols such as
+.Ql \&.
+.Ql \&,
+.Ql \&;
+and
+.Ql _ .
+.Pp
+The
+.Ar value
+string consists of the string following the
+.Ql =
+character until the end of the line with any leading and trailing
+whitespace removed.
+.Pp
+The value string undergoes variable expansion.
+This can be done by including substrings of the form
+.Pf $ Ar name
+or
+.Pf $ Brq Ar name :
+this will substitute the value of the named variable in the current
+section.
+It is also possible to substitute a value from another section using the
+syntax
+.Pf $ Ar section Ns :: Ns Ar name
+or
+.Pf $ Brq Ar section Ns :: Ns Ar name .
+By using the form
+.Pf $ Ic ENV Ns :: Ns Ar name ,
+environment variables can be substituted.
+It is also possible to assign values to environment variables by using
+the name
+.Ic ENV Ns :: Ns Ar name .
+This will work if the program looks up environment variables using
+the CONF library instead of calling
+.Xr getenv 3
+directly.
+.Pp
+It is possible to escape certain characters by using any kind of quote
+or the
+.Ql \e
+character.
+By making the last character of a line a
+.Ql \e ,
+a
+.Ar value
+string can be spread across multiple lines.
+In addition the sequences
+.Ql \en ,
+.Ql \er ,
+.Ql \eb ,
+and
+.Ql \et
+are recognized.
+.Sh OPENSSL LIBRARY CONFIGURATION
+Applications can automatically configure certain aspects of OpenSSL
+using the master OpenSSL configuration file, or optionally an
+alternative configuration file.
+The
+.Xr openssl 1
+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
+.Ic openssl_conf
+which is used by the
+.Xr openssl 1
+utility.
+Other applications may use an alternative name such as
+.Sy myapplicaton_conf .
+.Pp
+The configuration section should consist of a set of name value pairs
+which contain specific module configuration information.
+The
+.Ar name
+represents the name of the configuration module.
+The meaning of the
+.Ar value
+is module specific: it may, for example, represent a further
+configuration section containing configuration module specific
+information.
+For example:
+.Bd -literal -offset indent
+openssl_conf = openssl_init
+
+[openssl_init]
+oid_section = new_oids
+engines = engine_section
+
+[new_oids]
+\&... new oids here ...
+
+[engine_section]
+\&... engine stuff here ...
+.Ed
+.Pp
+The features of each configuration module are described below.
+.Ss ASN1 Object Configuration Module
+This module has the name
+.Ic oid_section .
+The value of this variable points to a section containing name value
+pairs of OIDs: the name is the OID short and long name, the value is the
+numerical form of the OID.
+Although some of the
+.Xr openssl 1
+utility subcommands already have their own ASN1 OBJECT section
+functionality, not all do.
+By using the ASN1 OBJECT configuration module, all the
+.Xr openssl 1
+utility subcommands can see the new objects as well as any compliant
+applications.
+For example:
+.Bd -literal -offset indent
+[new_oids]
+some_new_oid = 1.2.3.4
+some_other_oid = 1.2.3.5
+.Ed
+.Pp
+It is also possible to set the value to the long name followed by a
+comma and the numerical OID form.
+For example:
+.Pp
+.Dl shortName = some object long name, 1.2.3.4
+.Ss Engine Configuration Module
+This ENGINE configuration module has the name
+.Ic engines .
+The value of this variable points to a section containing further ENGINE
+configuration information.
+.Pp
+The section pointed to by
+.Ic engines
+is a table of engine names (though see
+.Ic engine_id
+below) and further sections containing configuration information
+specific to each ENGINE.
+.Pp
+Each ENGINE specific section is used to set default algorithms, load
+dynamic, perform initialization and send ctrls.
+The actual operation performed depends on the command
+name which is the name of the name value pair.
+The currently supported commands are listed below.
+.Pp
+For example:
+.Bd -literal -offset indent
+[engine_section]
+# Configure ENGINE named "foo"
+foo = foo_section
+# Configure ENGINE named "bar"
+bar = bar_section
+
+[foo_section]
+\&... foo ENGINE specific commands ...
+
+[bar_section]
+\&... "bar" ENGINE specific commands ...
+.Ed
+.Pp
+The command
+.Ic engine_id
+is used to give the ENGINE name.
+If used this command must be first.
+For example:
+.Bd -literal -offset indent
+[engine_section]
+# This would normally handle an ENGINE named "foo"
+foo = foo_section
+
+[foo_section]
+# Override default name and use "myfoo" instead.
+engine_id = myfoo
+.Ed
+.Pp
+The command
+.Ic dynamic_path
+loads and adds an ENGINE from the given path.
+It is equivalent to sending the ctrls
+.Sy SO_PATH
+with the path argument followed by
+.Sy LIST_ADD
+with value 2 and
+.Sy LOAD
+to the dynamic ENGINE. If this is not the required behaviour then
+alternative ctrls can be sent directly to the dynamic ENGINE using ctrl
+commands.
+.Pp
+The command
+.Ic init
+determines whether to initialize the ENGINE.
+If the value is 0, the ENGINE will not be initialized.
+If it is 1, an attempt is made to initialized the ENGINE immediately.
+If the
+.Ic init
+command is not present, then an attempt will be made to initialize
+the ENGINE after all commands in its section have been processed.
+.Pp
+The command
+.Ic default_algorithms
+sets the default algorithms an ENGINE will supply using the functions
+.Xr ENGINE_set_default_string 3 .
+.Pp
+If the name matches none of the above command names it is assumed
+to be a ctrl command which is sent to the ENGINE.
+The value of the command is the argument to the ctrl command.
+If the value is the string
+.Cm EMPTY ,
+then no value is sent to the command.
+.Pp
+For example:
+.Bd -literal -offset indent
+[engine_section]
+# Configure ENGINE named "foo"
+foo = foo_section
+
+[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
+.Ed
+.Ss SSL Configuration Module
+This module has the name
+.Ic ssl_conf
+which points to a section containing SSL configurations.
+.Pp
+Each line in the SSL configuration section contains the name of the
+configuration and the section containing it.
+.Pp
+Each configuration section consists of command value pairs for
+.Vt SSL_CONF .
+Each pair will be passed to a
+.Vt SSL_CTX
+or
+.Vt SSL
+structure if it calls
+.Xr SSL_CTX_config 3
+or
+.Xr SSL_config 3
+with the appropriate configuration name.
+.Pp
+Note: any characters before an initial dot in the configuration section
+are ignored so the same command can be used multiple times.
+.Pp
+For example:
+.Bd -literal -offset indent
+ssl_conf = ssl_sect
+
+[ssl_sect]
+server = server_section
+
+[server_section]
+RSA.Certificate = server-rsa.pem
+ECDSA.Certificate = server-ecdsa.pem
+Ciphers = ALL:!RC4
+.Ed
+.Sh FILES
+.Bl -tag -width /etc/ssl/openssl.cnf -compact
+.It Pa /etc/ssl/openssl.cnf
+standard configuration file
+.El
+.Sh EXAMPLES
+Here is a sample configuration file using some of the features
+mentioned above:
+.Bd -literal -offset indent
+# This is the default section.
+HOME=/temp
+RANDFILE= ${ENV::HOME}/.rnd
+configdir=$ENV::HOME/config
+
+[ section_one ]
+# We are now in section one.
+
+# Quotes permit leading and trailing whitespace
+any = " any variable name "
+
+other = A string that can \e
+cover several lines \e
+by including \e\e characters
+
+message = Hello World\en
+
+[ section_two ]
+greeting = $section_one::message
+.Ed
+.Pp
+This next example shows how to expand environment variables safely.
+.Pp
+Suppose you want a variable called
+.Sy tmpfile
+to refer to a temporary filename.
+The directory it is placed in can determined by the
+.Ev TEMP
+or
+.Ev TMP
+environment variables but they may not be set to any value at all.
+If you just include the environment variable names and the variable
+doesn't exist then this will cause an error when an attempt is made to
+load the configuration file.
+By making use of the default section both values can be looked up with
+.Ev TEMP
+taking priority and
+.Pa /tmp
+used if neither is defined:
+.Bd -literal -offset indent
+TMP=/tmp
+# The above value is used if TMP isn't in the environment
+TEMP=$ENV::TMP
+# The above value is used if TEMP isn't in the environment
+tmpfile=${ENV::TEMP}/tmp.filename
+.Ed
+.Pp
+More complex OpenSSL library configuration.
+Add OID:
+.Bd -literal -offset indent
+# Default appname: should match "appname" parameter (if any)
+# supplied to CONF_modules_load_file et al.
+openssl_conf = openssl_conf_section
+
+[openssl_conf_section]
+# Configuration module list
+alg_section = evp_sect
+oid_section = new_oids
+
+[new_oids]
+# New OID, just short name
+newoid1 = 1.2.3.4.1
+# New OID shortname and long name
+newoid2 = New OID 2 long name, 1.2.3.4.2
+.Ed
+.Pp
+The above examples can be used with any application supporting library
+configuration if "openssl_conf" is modified to match the appropriate
+"appname".
+.Pp
+For example if the second sample file above is saved to "example.cnf"
+then the command line:
+.Pp
+.Dl OPENSSL_CONF=example.cnf openssl asn1parse -genstr OID:1.2.3.4.1
+.Pp
+will output:
+.Dl 0:d=0  hl=2 l=   4 prim: OBJECT            :newoid1
+.Pp
+showing that the OID "newoid1" has been added as "1.2.3.4.1".
+.Sh SEE ALSO
+.Xr openssl 1 ,
+.Xr CONF_modules_load_file 3 ,
+.Xr x509v3.cnf 5
+.Sh CAVEATS
+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 also happen if an attempt is made to expand an environment
+variable that doesn't exist.
+For example, in a previous version of OpenSSL the default OpenSSL
+master configuration file used the value of
+.Ev HOME
+which may not be defined on non Unix systems and would cause an error.
+.Pp
+This can be worked around by including a default section to provide
+a default value: then if the environment lookup fails, the default
+value will be used instead.
+For this to work properly, the default value must be defined earlier
+in the configuration file than the expansion.
+See the
+.Sx EXAMPLES
+section for an example of how to do this.
+.Pp
+If the same variable is defined more than once in the same section,
+then all but the last value will be silently ignored.
+In certain circumstances such as with DNs, the same field may occur
+multiple times.
+This is usually worked around by ignoring any characters before an
+initial
+.Ql \&. ,
+for example:
+.Bd -literal -offset indent
+1.OU="My first OU"
+2.OU="My Second OU"
+.Ed
+.Sh BUGS
+Currently there is no way to include characters using the octal
+.Pf \e Ar nnn
+form.
+Strings are all NUL terminated, so NUL bytes cannot form part of
+the value.
+.Pp
+The escaping isn't quite right: if you want to use sequences like
+.Ql \en ,
+you can't use any quote escaping on the same line.
+.Pp
+Files are loaded in a single pass.
+This means that an variable expansion will only work if the variables
+referenced are defined earlier in the file.
diff --git a/src/lib/libcrypto/man/x509v3.cnf.5 b/src/lib/libcrypto/man/x509v3.cnf.5
new file mode 100644
index 0000000000..22e013a87e
--- /dev/null
+++ b/src/lib/libcrypto/man/x509v3.cnf.5
@@ -0,0 +1,731 @@
+.\"     $OpenBSD: x509v3.cnf.5,v 1.1 2016/12/11 18:06:09 schwarze Exp $
+.\"     OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400
+.\"
+.\" This file was written by Dr. Stephen Henson <steve@openssl.org>.
+.\" Copyright (c) 2004, 2006, 2013, 2014, 2015, 2016 The OpenSSL Project.
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\"
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\"
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in
+.\"    the documentation and/or other materials provided with the
+.\"    distribution.
+.\"
+.\" 3. All advertising materials mentioning features or use of this
+.\"    software must display the following acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
+.\"
+.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
+.\"    endorse or promote products derived from this software without
+.\"    prior written permission. For written permission, please contact
+.\"    openssl-core@openssl.org.
+.\"
+.\" 5. Products derived from this software may not be called "OpenSSL"
+.\"    nor may "OpenSSL" appear in their names without prior written
+.\"    permission of the OpenSSL Project.
+.\"
+.\" 6. Redistributions of any form whatsoever must retain the following
+.\"    acknowledgment:
+.\"    "This product includes software developed by the OpenSSL Project
+.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
+.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
+.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
+.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+.\" OF THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd $Mdocdate: December 11 2016 $
+.Dt X509V3.CNF 5
+.Os
+.Sh NAME
+.Nm x509v3.cnf
+.Nd X.509 V3 certificate extension configuration format
+.Sh DESCRIPTION
+Several of the OpenSSL utilities can add extensions to a certificate or
+certificate request based on the contents of a configuration file.
+The file format is based on the
+.Xr openssl.cnf 5
+format.
+.Pp
+Typically the application will contain an option to point to an
+extension section.
+Each line of the extension section takes the form:
+.Pp
+.D1 Ar extension_name Ns = Ns Oo Cm critical , Oc Ar extension_options
+.Pp
+If
+.Cm critical
+is present, then the extension will be critical.
+.Pp
+The format of
+.Ar extension_options
+depends on the value of
+.Ar extension_name .
+.Pp
+There are four main types of extension: string extensions, multi-valued
+extensions, raw extensions, and arbitrary extensions.
+.Pp
+String extensions simply have a string which contains either the value
+itself or how it is obtained.
+For example:
+.Pp
+.Dl nsComment="This is a Comment"
+.Pp
+Multi-valued extensions have a short form and a long form.
+The short form is a list of names and values:
+.Pp
+.Dl basicConstraints=critical,CA:true,pathlen:1
+.Pp
+The long form allows the values to be placed in a separate section:
+.Bd -literal -offset indent
+basicConstraints=critical,@bs_section
+
+[bs_section]
+CA=true
+pathlen=1
+.Ed
+.Pp
+Both forms are equivalent.
+.Pp
+The syntax of raw extensions is governed by the extension code:
+it can for example contain data in multiple sections.
+The correct syntax to use is defined by the extension code itself:
+check out the certificate policies extension for an example.
+.Pp
+If an extension type is unsupported, then the arbitrary extension
+syntax must be used, see the
+.Sx ARBITRARY EXTENSIONS
+section for more details.
+.Sh STANDARD EXTENSIONS
+The following sections describe each supported extension in detail.
+.Ss Basic constraints
+This is a multi-valued extension which indicates whether a certificate
+is a CA certificate.
+The first (mandatory) name is
+.Ic CA
+followed by
+.Cm TRUE
+or
+.Cm FALSE .
+If
+.Ic CA
+is
+.Cm TRUE ,
+then an optional
+.Ic pathlen
+name followed by an non-negative value can be included.
+For example:
+.Bd -literal -offset indent
+basicConstraints=CA:TRUE
+basicConstraints=CA:FALSE
+basicConstraints=critical,CA:TRUE, pathlen:0
+.Ed
+.Pp
+A CA certificate must include the
+.Ic basicConstraints
+value with the
+.Ic CA
+field set to
+.Cm TRUE .
+An end user certificate must either set
+.Ic CA
+to
+.Cm FALSE
+or exclude the extension entirely.
+Some software may require the inclusion of
+.Ic basicConstraints
+with
+.Ic CA
+set to
+.Cm FALSE
+for end entity certificates.
+.Pp
+The
+.Ic pathlen
+parameter indicates the maximum number of CAs that can appear below
+this one in a chain.
+So if you have a CA with a
+.Ic pathlen
+of zero it can only be used to sign end user certificates and not
+further CAs.
+.Ss Key usage
+Key usage is a multi-valued extension consisting of a list of names of
+the permitted key usages.
+.Pp
+The supported names are:
+.Ic digitalSignature ,
+.Ic nonRepudiation ,
+.Ic keyEncipherment ,
+.Ic dataEncipherment ,
+.Ic keyAgreement ,
+.Ic keyCertSign ,
+.Ic cRLSign ,
+.Ic encipherOnly ,
+and
+.Ic decipherOnly .
+Examples:
+.Bd -literal -offset indent
+keyUsage=digitalSignature, nonRepudiation
+keyUsage=critical, keyCertSign
+.Ed
+.Ss Extended key usage
+This extensions consists of a list of usages indicating purposes for
+which the certificate public key can be used for.
+.Pp
+These can either be object short names or the dotted numerical form of OIDs.
+While any OID can be used, only certain values make sense.
+In particular the following PKIX, NS and MS values are meaningful:
+.Bl -column emailProtection
+.It Em value Ta Em meaning
+.It Ic serverAuth      Ta SSL/TLS web server authentication
+.It Ic clientAuth      Ta SSL/TLS web client authentication
+.It Ic codeSigning     Ta code signing
+.It Ic emailProtection Ta E-mail protection (S/MIME)
+.It Ic timeStamping    Ta trusted timestamping
+.It Ic OCSPSigning     Ta OCSP signing
+.It Ic ipsecIKE        Ta IPsec internet key exchange
+.It Ic msCodeInd       Ta Microsoft individual code signing (authenticode)
+.It Ic msCodeCom       Ta Microsoft commercial code signing (authenticode)
+.It Ic msCTLSign       Ta Microsoft trust list signing
+.It Ic msEFS           Ta Microsoft encrypted file system
+.El
+.Pp
+Examples:
+.Bd -literal -offset indent
+extendedKeyUsage=critical,codeSigning,1.2.3.4
+extendedKeyUsage=serverAuth,clientAuth
+.Ed
+.Ss Subject key identifier
+This is really a string extension and can take two possible values.
+Either the word
+.Cm hash
+which will automatically follow the guidelines in RFC 3280
+or a hex string giving the extension value to include.
+The use of the hex string is strongly discouraged.
+Example:
+.Pp
+.Dl subjectKeyIdentifier=hash
+.Ss Authority key identifier
+The authority key identifier extension permits two options,
+.Cm keyid
+and
+.Cm issuer :
+both can take the optional value
+.Cm always .
+.Pp
+If the
+.Cm keyid
+option is present, an attempt is made to copy the subject
+key identifier from the parent certificate.
+If the value
+.Cm always
+is present, then an error is returned if the option fails.
+.Pp
+The
+.Cm issuer
+option copies the issuer and serial number from the issuer certificate.
+This will only be done if the
+.Cm keyid
+option fails or is not included unless the
+.Cm always
+flag will always include the value.
+Example:
+.Pp
+.Dl authorityKeyIdentifier=keyid,issuer
+.Ss Subject alternative name
+The subject alternative name extension allows various literal values to
+be included in the configuration file.
+These include
+.Ic email
+(an email address),
+.Ic URI
+(a uniform resource indicator),
+.Ic DNS
+(a DNS domain name),
+.Ic RID
+(a registered ID: OBJECT IDENTIFIER),
+.Ic IP
+(an IP address),
+.Ic dirName
+(a distinguished name), and
+.Ic otherName .
+.Pp
+The
+.Ic email
+option include a special
+.Cm copy
+value.
+This will automatically include any email addresses contained in the
+certificate subject name in the extension.
+.Pp
+The IP address used in the
+.Ic IP
+options can be in either IPv4 or IPv6 format.
+.Pp
+The value of
+.Ic dirName
+should point to a section containing the distinguished name to use as a
+set of name value pairs.
+Multi values AVAs can be formed by prefacing the name with a
+.Ql +
+character.
+.Pp
+.Ic otherName
+can include arbitrary data associated with an OID: the value should
+be the OID followed by a semicolon and the content in standard
+.Xr ASN1_generate_nconf 3
+format.
+Examples:
+.Bd -literal -offset 2n
+subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
+subjectAltName=IP:192.168.7.1
+subjectAltName=IP:13::17
+subjectAltName=email:my@other.address,RID:1.2.3.4
+subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
+
+subjectAltName=dirName:dir_sect
+
+[dir_sect]
+C=UK
+O=My Organization
+OU=My Unit
+CN=My Name
+.Ed
+.Ss Issuer alternative name
+The issuer alternative name option supports all the literal options of
+subject alternative name.
+It does not support the
+.Ic email : Ns Cm copy
+option because that would not make sense.
+It does support an additional
+.Ic issuer : Ns Cm copy
+option that will copy all the subject alternative name values from
+the issuer certificate (if possible).
+Example:
+.Pp
+.Dl issuserAltName = issuer:copy
+.Ss Authority info access
+The authority information access extension gives details about how to
+access certain information relating to the CA.
+Its syntax is
+.Ar accessOID ; location
+where
+.Ar location
+has the same syntax as subject alternative name (except that
+.Ic email : Ns Cm copy
+is not supported).
+.Ar accessOID
+can be any valid OID but only certain values are meaningful,
+for example
+.Cm OCSP
+and
+.Cm caIssuers .
+Example:
+.Bd -literal -offset indent
+authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
+authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
+.Ed
+.Ss CRL distribution points
+This is a multi-valued extension whose options can be either in
+.Ar name : Ns Ar value
+pair form using the same form as subject alternative name or a
+single value representing a section name containing all the
+distribution point fields.
+.Pp
+For a
+.Ar name : Ns Ar value
+pair a new DistributionPoint with the fullName field set to the
+given value, both the cRLissuer and reasons fields are omitted in
+this case.
+.Pp
+In the single option case, the section indicated contains values
+for each field.
+In this section:
+.Pp
+If the name is
+.Ic fullname ,
+the value field should contain the full name of the distribution
+point in the same format as subject alternative name.
+.Pp
+If the name is
+.Ic relativename ,
+then the value field should contain a section name whose contents
+represent a DN fragment to be placed in this field.
+.Pp
+The name
+.Ic CRLIssuer ,
+if present, should contain a value for this field in subject
+alternative name format.
+.Pp
+If the name is
+.Ic reasons ,
+the value field should consist of a comma separated field containing
+the reasons.
+Valid reasons are:
+.Cm keyCompromise ,
+.Cm CACompromise ,
+.Cm affiliationChanged ,
+.Cm superseded ,
+.Cm cessationOfOperation ,
+.Cm certificateHold ,
+.Cm privilegeWithdrawn ,
+and
+.Cm AACompromise .
+.Pp
+Simple examples:
+.Bd -literal -offset indent
+crlDistributionPoints=URI:http://myhost.com/myca.crl
+crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
+.Ed
+.Pp
+Full distribution point example:
+.Bd -literal -offset indent
+crlDistributionPoints=crldp1_section
+
+[crldp1_section]
+fullname=URI:http://myhost.com/myca.crl
+CRLissuer=dirName:issuer_sect
+reasons=keyCompromise, CACompromise
+
+[issuer_sect]
+C=UK
+O=Organisation
+CN=Some Name
+.Ed
+.Ss Issuing distribution point
+This extension should only appear in CRLs.
+It is a multi-valued extension whose syntax is similar to the "section"
+pointed to by the CRL distribution points extension with a few
+differences.
+.Pp
+The names
+.Ic reasons
+and
+.Ic CRLissuer
+are not recognized.
+.Pp
+The name
+.Ic onlysomereasons
+is accepted which sets this field.
+The value is in the same format as the CRL distribution point
+.Ic reasons
+field.
+.Pp
+The names
+.Ic onlyuser ,
+.Ic onlyCA ,
+.Ic onlyAA ,
+and
+.Ic indirectCRL
+are also accepted.
+The values should be a boolean values
+.Cm ( TRUE
+or
+.Cm FALSE )
+to indicate the value of the corresponding field.
+Example:
+.Bd -literal -offset indent
+issuingDistributionPoint=critical, @idp_section
+
+[idp_section]
+fullname=URI:http://myhost.com/myca.crl
+indirectCRL=TRUE
+onlysomereasons=keyCompromise, CACompromise
+
+[issuer_sect]
+C=UK
+O=Organisation
+CN=Some Name
+.Ed
+.Ss Certificate policies
+This is a raw extension.
+All the fields of this extension can be set by using the appropriate
+syntax.
+.Pp
+If you follow the PKIX recommendations and just using one OID, then you
+just include the value of that OID.
+Multiple OIDs can be set separated by commas, for example:
+.Pp
+.Dl certificatePolicies= 1.2.4.5, 1.1.3.4
+.Pp
+If you wish to include qualifiers, then the policy OID and qualifiers
+need to be specified in a separate section: this is done by using the
+.Pf @ Ar section
+syntax instead of a literal OID value.
+.Pp
+The section referred to must include the policy OID using the name
+.Ic policyIdentifier .
+.Ic CPSuri
+qualifiers can be included using the syntax:
+.Pp
+.D1 Ic CPS . Ns Ar nnn Ns = Ns Ar value
+.Pp
+.Ic userNotice
+qualifiers can be set using the syntax:
+.Pp
+.D1 Ic userNotice . Ns Ar nnn Ns =@ Ns Ar notice
+.Pp
+The value of the
+.Ic userNotice
+qualifier is specified in the relevant section.
+This section can include
+.Ic explicitText ,
+.Ic organization ,
+and
+.Ic noticeNumbers
+options.
+.Ic explicitText
+and
+.Ic organization
+are text strings,
+.Ic noticeNumbers
+is a comma separated list of numbers.
+The
+.Ic organization
+and
+.Ic noticeNumbers
+options (if included) must
+.Em both
+be present.
+If you use the
+.Ic userNotice
+option with IE5 then you need the
+.Ic ia5org
+option at the top level to modify the encoding: otherwise it will
+not be interpreted properly.
+Example:
+.Bd -literal -offset indent
+certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
+
+[polsect]
+policyIdentifier = 1.3.5.8
+CPS.1="http://my.host.name/"
+CPS.2="http://my.your.name/"
+userNotice.1=@notice
+
+[notice]
+explicitText="Explicit Text Here"
+organization="Organisation Name"
+noticeNumbers=1,2,3,4
+.Ed
+.Pp
+The
+.Ic ia5org
+option changes the type of the
+.Ic organization
+field.
+In RFC 2459, it can only be of type DisplayText.
+In RFC 3280, IA5Strring is also permissible.
+Some software (for example some versions of MSIE) may require
+.Ic ia5org .
+.Ss Policy constraints
+This is a multi-valued extension which consists of the names
+.Ic requireExplicitPolicy
+or
+.Ic inhibitPolicyMapping
+and a non-negative integer value.
+At least one component must be present.
+Example:
+.Pp
+.Dl policyConstraints = requireExplicitPolicy:3
+.Ss Inhibit any policy
+This is a string extension whose value must be a non-negative integer.
+Example:
+.Pp
+.Dl inhibitAnyPolicy = 2
+.Ss Name constraints
+The name constraints extension is a multi-valued extension.
+The name should begin with the word
+.Cm permitted
+or
+.Cm excluded
+followed by a semicolon.
+The rest of the name and the value follows the syntax of subjectAltName
+except
+.Ic email : Ns Cm copy
+is not supported and the
+.Ic IP
+form should consist of an IP addresses and subnet mask separated
+by a slash.
+Examples:
+.Bd -literal -offset indent
+nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
+nameConstraints=permitted;email:.somedomain.com
+nameConstraints=excluded;email:.com
+.Ed
+.Ss OCSP no check
+The OCSP no check extension is a string extension,
+but its value is ignored.
+Example:
+.Pp
+.Dl noCheck = ignored
+.Ss TLS Feature (aka must staple)
+This is a multi-valued extension consisting of a list of TLS extension
+identifiers.
+Each identifier may be a number in the range from 0 to 65535 or a
+supported name.
+When a TLS client sends a listed extension, the TLS server is expected
+to include that extension in its reply.
+.Pp
+The supported names are:
+.Cm status_request
+and
+.Cm status_request_v2 .
+Example:
+.Pp
+.Dl tlsfeature = status_request
+.Sh DEPRECATED EXTENSIONS
+The following extensions are non standard, Netscape specific and largely
+obsolete.
+Their use in new applications is discouraged.
+.Ss Netscape string extensions
+Netscape comment
+.Ic ( nsComment )
+is a string extension containing a comment which will be displayed when
+the certificate is viewed in some browsers.
+Example:
+.Pp
+.Dl nsComment = "Some Random Comment"
+.Pp
+Other supported extensions in this category are:
+.Ic nsBaseUrl ,
+.Ic nsRevocationUrl ,
+.Ic nsCaRevocationUrl ,
+.Ic nsRenewalUrl ,
+.Ic nsCaPolicyUrl ,
+and
+.Ic nsSslServerName .
+.Ss Netscape certificate type
+This is a multi-valued extensions which consists of a list of flags to
+be included.
+It was used to indicate the purposes for which a certificate could be
+used.
+The
+.Ic basicConstraints ,
+.Ic keyUsage ,
+and extended key usage extensions are now used instead.
+.Pp
+Acceptable values for
+.Ic nsCertType
+are:
+.Cm client ,
+.Cm server ,
+.Cm email ,
+.Cm objsign ,
+.Cm reserved ,
+.Cm sslCA ,
+.Cm emailCA ,
+.Cm objCA .
+.Sh ARBITRARY EXTENSIONS
+If an extension is not supported by the OpenSSL code, then it must
+be encoded using the arbitrary extension format.
+It is also possible to use the arbitrary format for supported
+extensions.
+Extreme care should be taken to ensure that the data is formatted
+correctly for the given extension type.
+.Pp
+There are two ways to encode arbitrary extensions.
+.Pp
+The first way is to use the word
+.Cm ASN1
+followed by the extension content using the same syntax as
+.Xr ASN1_generate_nconf 3 .
+For example:
+.Bd -literal -offset indent
+1.2.3.4=critical,ASN1:UTF8String:Some random data
+1.2.3.4=ASN1:SEQUENCE:seq_sect
+
+[seq_sect]
+field1 = UTF8:field1
+field2 = UTF8:field2
+.Ed
+.Pp
+It is also possible to use the word
+.Cm DER
+to include the raw encoded data in any extension.
+.Bd -literal -offset indent
+1.2.3.4=critical,DER:01:02:03:04
+1.2.3.4=DER:01020304
+.Ed
+.Pp
+The value following
+.Cm DER
+is a hex dump of the DER encoding of the extension.
+Any extension can be placed in this form to override the default behaviour.
+For example:
+.Pp
+.Dl basicConstraints=critical,DER:00:01:02:03
+.Sh FILES
+.Bl -tag -width /etc/ssl/x509v3.cnf -compact
+.It Pa /etc/ssl/x509v3.cnf
+standard configuration file
+.El
+.Sh SEE ALSO
+.Xr openssl 1 ,
+.Xr ASN1_generate_nconf 3 ,
+.Xr openssl.cnf 5
+.Sh HISTORY
+X509v3 extension code was first added to OpenSSL 0.9.2.
+.Sh CAVEATS
+There is no guarantee that a specific implementation will process a
+given extension.
+It may therefore sometimes be possible to use certificates for purposes
+prohibited by their extensions because a specific application does not
+recognize or honour the values of the relevant extensions.
+.Pp
+The
+.Cm DER
+and
+.Cm ASN1
+options should be used with caution.
+It is possible to create totally invalid extensions if they are not used
+carefully.
+.Pp
+If an extension is multi-value and a field value must contain a comma,
+the long form must be used.
+Otherwise the comma would be misinterpreted as a field separator.
+For example,
+.Pp
+.Dl subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
+.Pp
+will produce an error, but the following form is valid:
+.Bd -literal -offset indent
+subjectAltName=@subject_alt_section
+
+[subject_alt_section]
+subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
+.Ed
+.Pp
+Due to the behaviour of the OpenSSL CONF library, the same field
+name can only occur once in a section.
+That means that
+.Bd -literal -offset indent
+subjectAltName=@alt_section
+
+[alt_section]
+email=steve@here
+email=steve@there
+.Ed
+.Pp
+will only use the last value.
+This can be worked around by using the form:
+.Bd -literal -offset indent
+[alt_section]
+email.1=steve@here
+email.2=steve@there
+.Ed