aboutsummaryrefslogtreecommitdiff
path: root/secure/lib/libcrypto/man/man5
diff options
context:
space:
mode:
Diffstat (limited to 'secure/lib/libcrypto/man/man5')
-rw-r--r--secure/lib/libcrypto/man/man5/Makefile4
-rw-r--r--secure/lib/libcrypto/man/man5/config.5708
-rw-r--r--secure/lib/libcrypto/man/man5/fips_config.5236
-rw-r--r--secure/lib/libcrypto/man/man5/x509v3_config.5678
4 files changed, 1313 insertions, 313 deletions
diff --git a/secure/lib/libcrypto/man/man5/Makefile b/secure/lib/libcrypto/man/man5/Makefile
index 099b7fad81f1..8613df9675ac 100644
--- a/secure/lib/libcrypto/man/man5/Makefile
+++ b/secure/lib/libcrypto/man/man5/Makefile
@@ -1,3 +1,3 @@
-# $FreeBSD$
-# MAN+= config.5
+#MAN+= config.5
+MAN+= fips_config.5
MAN+= x509v3_config.5
diff --git a/secure/lib/libcrypto/man/man5/config.5 b/secure/lib/libcrypto/man/man5/config.5
new file mode 100644
index 000000000000..ea387fa315c5
--- /dev/null
+++ b/secure/lib/libcrypto/man/man5/config.5
@@ -0,0 +1,708 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.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. \*(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-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "CONFIG 5ossl"
+.TH CONFIG 5ossl "2023-09-19" "3.0.11" "OpenSSL"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+config \- OpenSSL CONF library configuration files
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+This page documents the syntax of OpenSSL configuration files,
+as parsed by \fBNCONF_load\fR\|(3) and related functions.
+This format is used by many of the OpenSSL commands, and to
+initialize the libraries when used by any application.
+.PP
+The first part describes the general syntax of the configuration
+files, and subsequent sections describe the semantics of individual
+modules. Other modules are described in \fBfips_config\fR\|(5) and
+\&\fBx509v3_config\fR\|(5).
+The syntax for defining \s-1ASN.1\s0 values is described in
+\&\fBASN1_generate_nconf\fR\|(3).
+.SH "SYNTAX"
+.IX Header "SYNTAX"
+A configuration file is a series of lines. Blank lines, and whitespace
+between the elements of a line, have no significance. A comment starts
+with a \fB#\fR character; the rest of the line is ignored. If the \fB#\fR
+is the first non-space character in a line, the entire line is ignored.
+.SS "Directives"
+.IX Subsection "Directives"
+Two directives can be used to control the parsing of configuration files:
+\&\fB.include\fR and \fB.pragma\fR.
+.PP
+For compatibility with older versions of OpenSSL, an equal sign after the
+directive will be ignored. Older versions will treat it as an assignment,
+so care should be taken if the difference in semantics is important.
+.PP
+A file can include other files using the include syntax:
+.PP
+.Vb 1
+\& .include [=] pathname
+.Ve
+.PP
+If \fBpathname\fR is a simple filename, that file is included directly at
+that point. Included files can have \fB.include\fR statements that specify
+other files. If \fBpathname\fR is a directory, all files within that directory
+that have a \f(CW\*(C`.cnf\*(C'\fR or \f(CW\*(C`.conf\*(C'\fR extension will be included. (This is only
+available on systems with \s-1POSIX IO\s0 support.) Any sub-directories found
+inside the \fBpathname\fR are \fBignored\fR. Similarly, if a file is opened
+while scanning a directory, and that file has an \fB.include\fR directive
+that specifies a directory, that is also ignored.
+.PP
+As a general rule, the \fBpathname\fR should be an absolute path; this can
+be enforced with the \fBabspath\fR and \fBincludedir\fR pragmas, described below.
+The environment variable \fB\s-1OPENSSL_CONF_INCLUDE\s0\fR, if it exists,
+is prepended to all relative pathnames.
+If the pathname is still relative, it is interpreted based on the
+current working directory.
+.PP
+To require all file inclusions to name absolute paths, use the following
+directive:
+.PP
+.Vb 1
+\& .pragma [=] abspath:value
+.Ve
+.PP
+The default behavior, where the \fBvalue\fR is \fBfalse\fR or \fBoff\fR, is to allow
+relative paths. To require all \fB.include\fR pathnames to be absolute paths,
+use a \fBvalue\fR of \fBtrue\fR or \fBon\fR.
+.PP
+In these files, the dollar sign, \fB$\fR, is used to reference a variable, as
+described below. On some platforms, however, it is common to treat \fB$\fR
+as a regular character in symbol names. Supporting this behavior can be
+done with the following directive:
+.PP
+.Vb 1
+\& .pragma [=] dollarid:value
+.Ve
+.PP
+The default behavior, where the \fBvalue\fR is \fBfalse\fR or \fBoff\fR, is to treat
+the dollarsign as indicating a variable name; \f(CW\*(C`foo$bar\*(C'\fR is interpreted as
+\&\f(CW\*(C`foo\*(C'\fR followed by the expansion of the variable \f(CW\*(C`bar\*(C'\fR. If \fBvalue\fR is
+\&\fBtrue\fR or \fBon\fR, then \f(CW\*(C`foo$bar\*(C'\fR is a single seven-character name and
+variable expansions must be specified using braces or parentheses.
+.PP
+.Vb 1
+\& .pragma [=] includedir:value
+.Ve
+.PP
+If a relative pathname is specified in the \fB.include\fR directive, and
+the \fB\s-1OPENSSL_CONF_INCLUDE\s0\fR environment variable doesn't exist, then
+the value of the \fBincludedir\fR pragma, if it exists, is prepended to the
+pathname.
+.SS "Settings"
+.IX Subsection "Settings"
+A configuration file is divided into a number of \fIsections\fR. A section
+begins with the section name in square brackets, and ends when a new
+section starts, or at the end of the file. The section name can consist
+of alphanumeric characters and underscores.
+Whitespace between the name and the brackets is removed.
+.PP
+The first section of a configuration file is special and is referred to
+as the \fBdefault\fR section. This section is usually unnamed and spans from
+the start of file until the first named section. When a name is being
+looked up, it is first looked up in the current or named section,
+and then the default section if necessary.
+.PP
+The environment is mapped onto a section called \fB\s-1ENV\s0\fR.
+.PP
+Within a section are a series of name/value assignments, described in more
+detail below. As a reminder, the square brackets shown in this example
+are required, not optional:
+.PP
+.Vb 7
+\& [ section ]
+\& name1 = This is value1
+\& name2 = Another value
+\& ...
+\& [ newsection ]
+\& name1 = New value1
+\& name3 = Value 3
+.Ve
+.PP
+The \fBname\fR can contain any alphanumeric characters as well as a few
+punctuation symbols such as \fB.\fR \fB,\fR \fB;\fR and \fB_\fR.
+Whitespace after the name and before the equal sign is ignored.
+.PP
+If a name is repeated in the same section, then all but the last
+value are ignored. In certain circumstances, such as with
+Certificate DNs, the same field may occur multiple times.
+In order to support this, commands like \fBopenssl\-req\fR\|(1) ignore any
+leading text that is preceded with a period. For example:
+.PP
+.Vb 2
+\& 1.OU = First OU
+\& 2.OU = Second OU
+.Ve
+.PP
+The \fBvalue\fR consists of the string following the \fB=\fR character until end
+of line with any leading and trailing whitespace removed.
+.PP
+The value string undergoes variable expansion. The text \f(CW$var\fR or \f(CW\*(C`${var}\*(C'\fR
+inserts the value of the named variable from the current section.
+To use a value from another section use \f(CW$section::name\fR
+or \f(CW\*(C`${section::name}\*(C'\fR.
+By using \f(CW$ENV::name\fR, the value of the specified environment
+variable will be substituted.
+.PP
+Variables must be defined before their value is referenced, otherwise
+an error is flagged and the file will not load.
+This can be worked around by specifying a default value in the \fBdefault\fR
+section before the variable is used.
+.PP
+Any name/value settings in an \fB\s-1ENV\s0\fR section are available
+to the configuration file, but are not propagated to the environment.
+.PP
+It is an error if the value ends up longer than 64k.
+.PP
+It is possible to escape certain characters by using a single \fB'\fR or
+double \fB"\fR quote around the value, or using a backslash \fB\e\fR before the
+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.
+.PP
+The expansion and escape rules as described above that apply to \fBvalue\fR
+also apply to the pathname of the \fB.include\fR directive.
+.SH "OPENSSL LIBRARY CONFIGURATION"
+.IX Header "OPENSSL LIBRARY CONFIGURATION"
+The sections below use the informal term \fImodule\fR to refer to a part
+of the OpenSSL functionality. This is not the same as the formal term
+\&\fI\s-1FIPS\s0 module\fR, for example.
+.PP
+The OpenSSL configuration looks up the value of \fBopenssl_conf\fR
+in the default section and takes that as the name of a section that specifies
+how to configure any modules in the library. It is not an error to leave
+any module in its default configuration. An application can specify a
+different name by calling \fBCONF_modules_load_file()\fR, for example, directly.
+.PP
+OpenSSL also looks up the value of \fBconfig_diagnostics\fR.
+If this exists and has a nonzero numeric value, any error suppressing flags
+passed to \fBCONF_modules_load()\fR will be ignored.
+This is useful for diagnosing misconfigurations but its use in
+production requires additional consideration. With this option enabled,
+a configuration error will completely prevent access to a service.
+Without this option and in the presence of a configuration error, access
+will be allowed but the desired configuration will \fBnot\fR be used.
+.PP
+.Vb 3
+\& # These must be in the default section
+\& config_diagnostics = 1
+\& openssl_conf = openssl_init
+\&
+\& [openssl_init]
+\& oid_section = oids
+\& providers = providers
+\& alg_section = evp_properties
+\& ssl_conf = ssl_configuration
+\& engines = engines
+\& random = random
+\&
+\& [oids]
+\& ... new oids here ...
+\&
+\& [providers]
+\& ... provider stuff here ...
+\&
+\& [evp_properties]
+\& ... EVP properties here ...
+\&
+\& [ssl_configuration]
+\& ... SSL/TLS configuration properties here ...
+\&
+\& [engines]
+\& ... engine properties here ...
+\&
+\& [random]
+\& ... random properties here ...
+.Ve
+.PP
+The semantics of each module are described below. The phrase \*(L"in the
+initialization section\*(R" refers to the section identified by the
+\&\fBopenssl_conf\fR or other name (given as \fBopenssl_init\fR in the
+example above). The examples below assume the configuration above
+is used to specify the individual sections.
+.SS "\s-1ASN.1\s0 Object Identifier Configuration"
+.IX Subsection "ASN.1 Object Identifier Configuration"
+The name \fBoid_section\fR in the initialization section names the section
+containing name/value pairs of \s-1OID\s0's.
+The name is the short name; the value is an optional long name followed
+by a comma, and the numeric value.
+While some OpenSSL commands have their own section for specifying \s-1OID\s0's,
+this section makes them available to all commands and applications.
+.PP
+.Vb 4
+\& [oids]
+\& shortName = a very long OID name, 1.2.3.4
+\& newoid1 = 1.2.3.4.1
+\& some_other_oid = 1.2.3.5
+.Ve
+.PP
+If a full configuration with the above fragment is in the file
+\&\fIexample.cnf\fR, then the following command line:
+.PP
+.Vb 1
+\& OPENSSL_CONF=example.cnf openssl asn1parse \-genstr OID:1.2.3.4.1
+.Ve
+.PP
+will output:
+.PP
+.Vb 1
+\& 0:d=0 hl=2 l= 4 prim: OBJECT :newoid1
+.Ve
+.PP
+showing that the \s-1OID\s0 \*(L"newoid1\*(R" has been added as \*(L"1.2.3.4.1\*(R".
+.SS "Provider Configuration"
+.IX Subsection "Provider Configuration"
+The name \fBproviders\fR in the initialization section names the section
+containing cryptographic provider configuration. The name/value assignments
+in this section each name a provider, and point to the configuration section
+for that provider. The provider-specific section is used to specify how
+to load the module, activate it, and set other parameters.
+.PP
+Within a provider section, the following names have meaning:
+.IP "\fBidentity\fR" 4
+.IX Item "identity"
+This is used to specify an alternate name, overriding the default name
+specified in the list of providers. For example:
+.Sp
+.Vb 2
+\& [providers]
+\& foo = foo_provider
+\&
+\& [foo_provider]
+\& identity = my_fips_module
+.Ve
+.IP "\fBmodule\fR" 4
+.IX Item "module"
+Specifies the pathname of the module (typically a shared library) to load.
+.IP "\fBactivate\fR" 4
+.IX Item "activate"
+If present, the module is activated. The value assigned to this name is not
+significant.
+.PP
+All parameters in the section as well as sub-sections are made
+available to the provider.
+.PP
+\fIDefault provider and its activation\fR
+.IX Subsection "Default provider and its activation"
+.PP
+If no providers are activated explicitly, the default one is activated implicitly.
+See \fBOSSL_PROVIDER\-default\fR\|(7) for more details.
+.PP
+If you add a section explicitly activating any other provider(s),
+you most probably need to explicitly activate the default provider,
+otherwise it becomes unavailable in openssl. It may make the system remotely unavailable.
+.SS "\s-1EVP\s0 Configuration"
+.IX Subsection "EVP Configuration"
+The name \fBalg_section\fR in the initialization section names the section
+containing algorithmic properties when using the \fB\s-1EVP\s0\fR \s-1API.\s0
+.PP
+Within the algorithm properties section, the following names have meaning:
+.IP "\fBdefault_properties\fR" 4
+.IX Item "default_properties"
+The value may be anything that is acceptable as a property query
+string for \fBEVP_set_default_properties()\fR.
+.IP "\fBfips_mode\fR (deprecated)" 4
+.IX Item "fips_mode (deprecated)"
+The value is a boolean that can be \fByes\fR or \fBno\fR. If the value is
+\&\fByes\fR, this is exactly equivalent to:
+.Sp
+.Vb 1
+\& default_properties = fips=yes
+.Ve
+.Sp
+If the value is \fBno\fR, nothing happens. Using this name is deprecated, and
+if used, it must be the only name in the section.
+.SS "\s-1SSL\s0 Configuration"
+.IX Subsection "SSL Configuration"
+The name \fBssl_conf\fR in the initialization section names the section
+containing the list of \s-1SSL/TLS\s0 configurations.
+As with the providers, each name in this section identifies a
+section with the configuration for that name. For example:
+.PP
+.Vb 4
+\& [ssl_configuration]
+\& server = server_tls_config
+\& client = client_tls_config
+\& system_default = tls_system_default
+\&
+\& [server_tls_config]
+\& ... configuration for SSL/TLS servers ...
+\&
+\& [client_tls_config]
+\& ... configuration for SSL/TLS clients ...
+.Ve
+.PP
+The configuration name \fBsystem_default\fR has a special meaning. If it
+exists, it is applied whenever an \fB\s-1SSL_CTX\s0\fR object is created. For example,
+to impose system-wide minimum \s-1TLS\s0 and \s-1DTLS\s0 protocol versions:
+.PP
+.Vb 3
+\& [tls_system_default]
+\& MinProtocol = TLSv1.2
+\& MinProtocol = DTLSv1.2
+.Ve
+.PP
+The minimum \s-1TLS\s0 protocol is applied to \fB\s-1SSL_CTX\s0\fR objects that are TLS-based,
+and the minimum \s-1DTLS\s0 protocol to those are DTLS-based.
+The same applies also to maximum versions set with \fBMaxProtocol\fR.
+.PP
+Each configuration section consists of name/value pairs that are parsed
+by \fB\fBSSL_CONF_cmd\fB\|(3)\fR, which will be called by \fBSSL_CTX_config()\fR or
+\&\fBSSL_config()\fR, appropriately. Note that any characters before an initial
+dot in the configuration section are ignored, so that the same command can
+be used multiple times. This probably is most useful for loading different
+key types, as shown here:
+.PP
+.Vb 3
+\& [server_tls_config]
+\& RSA.Certificate = server\-rsa.pem
+\& ECDSA.Certificate = server\-ecdsa.pem
+.Ve
+.SS "Engine Configuration"
+.IX Subsection "Engine Configuration"
+The name \fBengines\fR in the initialization section names the section
+containing the list of \s-1ENGINE\s0 configurations.
+As with the providers, each name in this section identifies an engine
+with the configuration for that engine.
+The engine-specific section is used to specify how to load the engine,
+activate it, and set other parameters.
+.PP
+Within an engine section, the following names have meaning:
+.IP "\fBengine_id\fR" 4
+.IX Item "engine_id"
+This is used to specify an alternate name, overriding the default name
+specified in the list of engines. If present, it must be first.
+For example:
+.Sp
+.Vb 2
+\& [engines]
+\& foo = foo_engine
+\&
+\& [foo_engine]
+\& engine_id = myfoo
+.Ve
+.IP "\fBdynamic_path\fR" 4
+.IX Item "dynamic_path"
+This 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 \fB2\fR 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.
+.IP "\fBinit\fR" 4
+.IX Item "init"
+This specifies whether to initialize the \s-1ENGINE.\s0 If the value is \fB0\fR the
+\&\s-1ENGINE\s0 will not be initialized, if the value is \fB1\fR an attempt is made
+to initialize
+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.
+.IP "\fBdefault_algorithms\fR" 4
+.IX Item "default_algorithms"
+This sets the default algorithms an \s-1ENGINE\s0 will supply using the function
+\&\fBENGINE_set_default_string()\fR.
+.PP
+All other names are taken to be the name of a ctrl command that is
+sent to the \s-1ENGINE,\s0 and the value is the argument passed with the command.
+The special value \fB\s-1EMPTY\s0\fR means no value is sent with the command.
+For example:
+.PP
+.Vb 2
+\& [engines]
+\& foo = foo_engine
+\&
+\& [foo_engine]
+\& dynamic_path = /some/path/fooengine.so
+\& some_ctrl = some_value
+\& default_algorithms = ALL
+\& other_ctrl = EMPTY
+.Ve
+.SS "Random Configuration"
+.IX Subsection "Random Configuration"
+The name \fBrandom\fR in the initialization section names the section
+containing the random number generator settings.
+.PP
+Within the random section, the following names have meaning:
+.IP "\fBrandom\fR" 4
+.IX Item "random"
+This is used to specify the random bit generator.
+For example:
+.Sp
+.Vb 2
+\& [random]
+\& random = CTR\-DRBG
+.Ve
+.Sp
+The available random bit generators are:
+.RS 4
+.IP "\fBCTR-DRBG\fR" 4
+.IX Item "CTR-DRBG"
+.PD 0
+.IP "\fBHASH-DRBG\fR" 4
+.IX Item "HASH-DRBG"
+.IP "\fBHMAC-DRBG\fR" 4
+.IX Item "HMAC-DRBG"
+.RE
+.RS 4
+.RE
+.IP "\fBcipher\fR" 4
+.IX Item "cipher"
+.PD
+This specifies what cipher a \fBCTR-DRBG\fR random bit generator will use.
+Other random bit generators ignore this name.
+The default value is \fB\s-1AES\-256\-CTR\s0\fR.
+.IP "\fBdigest\fR" 4
+.IX Item "digest"
+This specifies what digest the \fBHASH-DRBG\fR or \fBHMAC-DRBG\fR random bit
+generators will use. Other random bit generators ignore this name.
+.IP "\fBproperties\fR" 4
+.IX Item "properties"
+This sets the property query used when fetching the random bit generator and
+any underlying algorithms.
+.IP "\fBseed\fR" 4
+.IX Item "seed"
+This sets the randomness source that should be used. By default \fBSEED-SRC\fR
+will be used outside of the \s-1FIPS\s0 provider. The \s-1FIPS\s0 provider uses call backs
+to access the same randomness sources from outside the validated boundary.
+.IP "\fBseed_properties\fR" 4
+.IX Item "seed_properties"
+This sets the property query used when fetching the randomness source.
+.SH "EXAMPLES"
+.IX Header "EXAMPLES"
+This example shows how to use quoting and escaping.
+.PP
+.Vb 3
+\& # This is the default section.
+\& HOME = /temp
+\& configdir = $ENV::HOME/config
+\&
+\& [ 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
+.Ve
+.PP
+This example shows how to expand environment variables safely.
+In this example, the variable \fBtempfile\fR is intended to refer
+to a temporary file, and the environment variable \fB\s-1TEMP\s0\fR or
+\&\fB\s-1TMP\s0\fR, if present, specify the directory where the file
+should be put.
+Since the default section is checked if a variable does not
+exist, it is possible to set \fB\s-1TMP\s0\fR to default to \fI/tmp\fR, and
+\&\fB\s-1TEMP\s0\fR to default to \fB\s-1TMP\s0\fR.
+.PP
+.Vb 3
+\& # These two lines must be in the default section.
+\& TMP = /tmp
+\& TEMP = $ENV::TMP
+\&
+\& # This can be used anywhere
+\& tmpfile = ${ENV::TEMP}/tmp.filename
+.Ve
+.PP
+This example shows how to enforce \s-1FIPS\s0 mode for the application
+\&\fIsample\fR.
+.PP
+.Vb 1
+\& sample = fips_config
+\&
+\& [fips_config]
+\& alg_section = evp_properties
+\&
+\& [evp_properties]
+\& default_properties = "fips=yes"
+.Ve
+.SH "ENVIRONMENT"
+.IX Header "ENVIRONMENT"
+.IP "\fB\s-1OPENSSL_CONF\s0\fR" 4
+.IX Item "OPENSSL_CONF"
+The path to the config file, or the empty string for none.
+Ignored in set-user-ID and set-group-ID programs.
+.IP "\fB\s-1OPENSSL_ENGINES\s0\fR" 4
+.IX Item "OPENSSL_ENGINES"
+The path to the engines directory.
+Ignored in set-user-ID and set-group-ID programs.
+.IP "\fB\s-1OPENSSL_MODULES\s0\fR" 4
+.IX Item "OPENSSL_MODULES"
+The path to the directory with OpenSSL modules, such as providers.
+Ignored in set-user-ID and set-group-ID programs.
+.IP "\fB\s-1OPENSSL_CONF_INCLUDE\s0\fR" 4
+.IX Item "OPENSSL_CONF_INCLUDE"
+The optional path to prepend to all \fB.include\fR paths.
+.SH "BUGS"
+.IX Header "BUGS"
+There is no way to include characters using the octal \fB\ennn\fR form. Strings
+are all null terminated so nulls cannot form part of the value.
+.PP
+The escaping isn't quite right: if you want to use sequences like \fB\en\fR
+you can't use any quote escaping on the same line.
+.PP
+The limit that only one directory can be opened and read at a time
+can be considered a bug and should be fixed.
+.SH "HISTORY"
+.IX Header "HISTORY"
+An undocumented \s-1API, \fBNCONF_WIN32\s0()\fR, used a slightly different set
+of parsing rules there were intended to be tailored to
+the Microsoft Windows platform.
+Specifically, the backslash character was not an escape character and
+could be used in pathnames, only the double-quote character was recognized,
+and comments began with a semi-colon.
+This function was deprecated in OpenSSL 3.0; applications with
+configuration files using that syntax will have to be modified.
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBopenssl\-x509\fR\|(1), \fBopenssl\-req\fR\|(1), \fBopenssl\-ca\fR\|(1),
+\&\fBopenssl\-fipsinstall\fR\|(1),
+\&\fBASN1_generate_nconf\fR\|(3),
+\&\fBEVP_set_default_properties\fR\|(3),
+\&\fBCONF_modules_load\fR\|(3),
+\&\fBCONF_modules_load_file\fR\|(3),
+\&\fBfips_config\fR\|(5), and
+\&\fBx509v3_config\fR\|(5).
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file \s-1LICENSE\s0 in the source distribution or at
+<https://www.openssl.org/source/license.html>.
diff --git a/secure/lib/libcrypto/man/man5/fips_config.5 b/secure/lib/libcrypto/man/man5/fips_config.5
new file mode 100644
index 000000000000..71c6014ae588
--- /dev/null
+++ b/secure/lib/libcrypto/man/man5/fips_config.5
@@ -0,0 +1,236 @@
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
+.\"
+.\" Standard preamble:
+.\" ========================================================================
+.de Sp \" Vertical space (when we can't use .PP)
+.if t .sp .5v
+.if n .sp
+..
+.de Vb \" Begin verbatim text
+.ft CW
+.nf
+.ne \\$1
+..
+.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. \*(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-
+.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
+.ie n \{\
+. ds -- \(*W-
+. ds PI pi
+. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
+. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
+. ds L" ""
+. ds R" ""
+. ds C` ""
+. ds C' ""
+'br\}
+.el\{\
+. ds -- \|\(em\|
+. ds PI \(*p
+. ds L" ``
+. ds R" ''
+. ds C`
+. ds C'
+'br\}
+.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
+.\" If the F register is >0, we'll generate index entries on stderr for
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
+.\" entries marked with X<> in POD. Of course, you'll have to process the
+.\" output yourself in some meaningful fashion.
+.\"
+.\" Avoid warning from groff about undefined register 'F'.
+.de IX
+..
+.nr rF 0
+.if \n(.g .if rF .nr rF 1
+.if (\n(rF:(\n(.g==0)) \{\
+. if \nF \{\
+. de IX
+. tm Index:\\$1\t\\n%\t"\\$2"
+..
+. if !\nF==2 \{\
+. nr % 0
+. nr F 2
+. \}
+. \}
+.\}
+.rr rF
+.\" Fear. Run. Save yourself. No user-serviceable parts.
+. \" fudge factors for nroff and troff
+.if n \{\
+. ds #H 0
+. ds #V .8m
+. ds #F .3m
+. ds #[ \f1
+. ds #] \fP
+.\}
+.if t \{\
+. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
+. ds #V .6m
+. ds #F 0
+. ds #[ \&
+. ds #] \&
+.\}
+. \" simple accents for nroff and troff
+.if n \{\
+. ds ' \&
+. ds ` \&
+. ds ^ \&
+. ds , \&
+. ds ~ ~
+. ds /
+.\}
+.if t \{\
+. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
+. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
+. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
+. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
+. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
+. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
+.\}
+. \" troff and (daisy-wheel) nroff accents
+.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
+.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
+.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
+.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
+.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
+.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
+.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
+.ds ae a\h'-(\w'a'u*4/10)'e
+.ds Ae A\h'-(\w'A'u*4/10)'E
+. \" corrections for vroff
+.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
+.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
+. \" for low resolution devices (crt and lpr)
+.if \n(.H>23 .if \n(.V>19 \
+\{\
+. ds : e
+. ds 8 ss
+. ds o a
+. ds d- d\h'-1'\(ga
+. ds D- D\h'-1'\(hy
+. ds th \o'bp'
+. ds Th \o'LP'
+. ds ae ae
+. ds Ae AE
+.\}
+.rm #[ #] #H #V #F C
+.\" ========================================================================
+.\"
+.IX Title "FIPS_CONFIG 5ossl"
+.TH FIPS_CONFIG 5ossl "2023-09-19" "3.0.11" "OpenSSL"
+.\" For nroff, turn off justification. Always turn off hyphenation; it makes
+.\" way too many mistakes in technical documents.
+.if n .ad l
+.nh
+.SH "NAME"
+fips_config \- OpenSSL FIPS configuration
+.SH "DESCRIPTION"
+.IX Header "DESCRIPTION"
+A separate configuration file, using the OpenSSL \fBconfig\fR\|(5) syntax,
+is used to hold information about the \s-1FIPS\s0 module. This includes a digest
+of the shared library file, and status about the self-testing.
+This data is used automatically by the module itself for two
+purposes:
+.IP "\- Run the startup \s-1FIPS\s0 self-test known answer tests (\s-1KATS\s0)." 4
+.IX Item "- Run the startup FIPS self-test known answer tests (KATS)."
+This is normally done once, at installation time, but may also be set up to
+run each time the module is used.
+.IP "\- Verify the module's checksum." 4
+.IX Item "- Verify the module's checksum."
+This is done each time the module is used.
+.PP
+This file is generated by the \fBopenssl\-fipsinstall\fR\|(1) program, and
+used internally by the \s-1FIPS\s0 module during its initialization.
+.PP
+The following options are supported. They should all appear in a section
+whose name is identified by the \fBfips\fR option in the \fBproviders\fR
+section, as described in \*(L"Provider Configuration Module\*(R" in \fBconfig\fR\|(5).
+.IP "\fBactivate\fR" 4
+.IX Item "activate"
+If present, the module is activated. The value assigned to this name is not
+significant.
+.IP "\fBinstall-version\fR" 4
+.IX Item "install-version"
+A version number for the fips install process. Should be 1.
+.IP "\fBconditional-errors\fR" 4
+.IX Item "conditional-errors"
+The \s-1FIPS\s0 module normally enters an internal error mode if any self test fails.
+Once this error mode is active, no services or cryptographic algorithms are
+accessible from this point on.
+Continuous tests are a subset of the self tests (e.g., a key pair test during key
+generation, or the \s-1CRNG\s0 output test).
+Setting this value to \f(CW0\fR allows the error mode to not be triggered if any
+continuous test fails. The default value of \f(CW1\fR will trigger the error mode.
+Regardless of the value, the operation (e.g., key generation) that called the
+continuous test will return an error code if its continuous test fails. The
+operation may then be retried if the error mode has not been triggered.
+.IP "\fBsecurity-checks\fR" 4
+.IX Item "security-checks"
+This indicates if run-time checks related to enforcement of security parameters
+such as minimum security strength of keys and approved curve names are used.
+A value of '1' will perform the checks, otherwise if the value is '0' the checks
+are not performed and \s-1FIPS\s0 compliance must be done by procedures documented in
+the relevant Security Policy.
+.IP "\fBmodule-mac\fR" 4
+.IX Item "module-mac"
+The calculated \s-1MAC\s0 of the \s-1FIPS\s0 provider file.
+.IP "\fBinstall-status\fR" 4
+.IX Item "install-status"
+An indicator that the self-tests were successfully run.
+This should only be written after the module has
+successfully passed its self tests during installation.
+If this field is not present, then the self tests will run when the module
+loads.
+.IP "\fBinstall-mac\fR" 4
+.IX Item "install-mac"
+A \s-1MAC\s0 of the value of the \fBinstall-status\fR option, to prevent accidental
+changes to that value.
+It is written-to at the same time as \fBinstall-status\fR is updated.
+.PP
+For example:
+.PP
+.Vb 8
+\& [fips_sect]
+\& activate = 1
+\& install\-version = 1
+\& conditional\-errors = 1
+\& security\-checks = 1
+\& module\-mac = 41:D0:FA:C2:5D:41:75:CD:7D:C3:90:55:6F:A4:DC
+\& install\-mac = FE:10:13:5A:D3:B4:C7:82:1B:1E:17:4C:AC:84:0C
+\& install\-status = INSTALL_SELF_TEST_KATS_RUN
+.Ve
+.SH "NOTES"
+.IX Header "NOTES"
+When using the \s-1FIPS\s0 provider, it is recommended that the
+\&\fBconfig_diagnostics\fR option is enabled to prevent accidental use of
+non-FIPS validated algorithms via broken or mistaken configuration.
+See \fBconfig\fR\|(5).
+.SH "SEE ALSO"
+.IX Header "SEE ALSO"
+\&\fBconfig\fR\|(5)
+\&\fBopenssl\-fipsinstall\fR\|(1)
+.SH "HISTORY"
+.IX Header "HISTORY"
+This functionality was added in OpenSSL 3.0.
+.SH "COPYRIGHT"
+.IX Header "COPYRIGHT"
+Copyright 2019\-2021 The OpenSSL Project Authors. All Rights Reserved.
+.PP
+Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file \s-1LICENSE\s0 in the source distribution or at
+<https://www.openssl.org/source/license.html>.
diff --git a/secure/lib/libcrypto/man/man5/x509v3_config.5 b/secure/lib/libcrypto/man/man5/x509v3_config.5
index db5009b0c8de..374dd11e34ff 100644
--- a/secure/lib/libcrypto/man/man5/x509v3_config.5
+++ b/secure/lib/libcrypto/man/man5/x509v3_config.5
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
+.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42)
.\"
.\" Standard preamble:
.\" ========================================================================
@@ -68,8 +68,6 @@
. \}
.\}
.rr rF
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
. \" fudge factors for nroff and troff
.if n \{\
@@ -132,8 +130,8 @@
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
-.IX Title "X509V3_CONFIG 5"
-.TH X509V3_CONFIG 5 "2022-06-21" "1.1.1p" "OpenSSL"
+.IX Title "X509V3_CONFIG 5ossl"
+.TH X509V3_CONFIG 5ossl "2023-09-19" "3.0.11" "OpenSSL"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
@@ -142,119 +140,169 @@
x509v3_config \- X509 V3 certificate extension configuration format
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
-Several of the OpenSSL utilities can add extensions to a certificate or
-certificate request based on the contents of a configuration file.
+Several OpenSSL commands can add extensions to a certificate or
+certificate request based on the contents of a configuration file
+and \s-1CLI\s0 options such as \fB\-addext\fR.
+The syntax of configuration files is described in \fBconfig\fR\|(5).
+The commands typically have an option to specify the name of the configuration
+file, and a section within that file; see the documentation of the
+individual command for details.
+.PP
+This page uses \fBextensions\fR as the name of the section, when needed
+in examples.
.PP
-Typically the application will contain an option to point to an extension
-section. Each line of the extension section takes the form:
+Each entry in the extension section takes the form:
.PP
.Vb 1
-\& extension_name=[critical,] extension_options
+\& name = [critical, ]value(s)
.Ve
.PP
-If \fBcritical\fR is present then the extension will be critical.
+If \fBcritical\fR is present then the extension will be marked as critical.
+.PP
+If multiple entries are processed for the same extension name,
+later entries override earlier ones with the same name.
.PP
-The format of \fBextension_options\fR depends on the value of \fBextension_name\fR.
+The format of \fBvalues\fR depends on the value of \fBname\fR, many have a
+type-value pairing where the type and value are separated by a colon.
+There are four main types of extension:
+.PP
+.Vb 4
+\& string
+\& multi\-valued
+\& raw
+\& arbitrary
+.Ve
.PP
-There are four main types of extension: \fIstring\fR extensions, \fImulti-valued\fR
-extensions, \fIraw\fR and \fIarbitrary\fR extensions.
+Each is described in the following paragraphs.
.PP
String extensions simply have a string which contains either the value itself
or how it is obtained.
.PP
-For example:
+Multi-valued extensions have a short form and a long form. The short form
+is a comma-separated list of names and values:
.PP
.Vb 1
-\& nsComment="This is a Comment"
+\& basicConstraints = critical, CA:true, pathlen:1
.Ve
.PP
-Multi-valued extensions have a short form and a long form. The short form
-is a list of names and values:
+The long form allows the values to be placed in a separate section:
.PP
-.Vb 1
-\& basicConstraints=critical,CA:true,pathlen:1
+.Vb 2
+\& [extensions]
+\& basicConstraints = critical, @basic_constraints
+\&
+\& [basic_constraints]
+\& CA = true
+\& pathlen = 1
.Ve
.PP
-The long form allows the values to be placed in a separate section:
+Both forms are equivalent.
+.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
.Vb 1
-\& basicConstraints=critical,@bs_section
+\& subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
+.Ve
+.PP
+will produce an error but the equivalent form:
+.PP
+.Vb 2
+\& [extensions]
+\& subjectAltName = @subject_alt_section
\&
-\& [bs_section]
+\& [subject_alt_section]
+\& subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
+.Ve
+.PP
+is valid.
+.PP
+OpenSSL does not support multiple occurrences of the same field within a
+section. In this example:
+.PP
+.Vb 2
+\& [extensions]
+\& subjectAltName = @alt_section
\&
-\& CA=true
-\& pathlen=1
+\& [alt_section]
+\& email = steve@example.com
+\& email = steve@example.org
.Ve
.PP
-Both forms are equivalent.
+will only recognize the last value. To specify multiple values append a
+numeric identifier, as shown here:
.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.
+.Vb 2
+\& [extensions]
+\& subjectAltName = @alt_section
+\&
+\& [alt_section]
+\& email.1 = steve@example.com
+\& email.2 = steve@example.org
+.Ve
+.PP
+The syntax of raw extensions is defined by the source code that parses
+the extension but should be documented.
+See \*(L"Certificate Policies\*(R" for an example of a raw extension.
.PP
-If an extension type is unsupported then the \fIarbitrary\fR extension syntax
-must be used, see the \s-1ARBITRARY EXTENSIONS\s0 section for more details.
+If an extension type is unsupported, then the \fIarbitrary\fR extension syntax
+must be used, see the \*(L"\s-1ARBITRARY EXTENSIONS\*(R"\s0 section for more details.
.SH "STANDARD EXTENSIONS"
.IX Header "STANDARD EXTENSIONS"
-The following sections describe each supported extension in detail.
-.SS "Basic Constraints."
-.IX Subsection "Basic Constraints."
-This is a multi valued extension which indicates whether a certificate is
-a \s-1CA\s0 certificate. The first (mandatory) name is \fB\s-1CA\s0\fR followed by \fB\s-1TRUE\s0\fR or
+The following sections describe the syntax of each supported extension.
+They do not define the semantics of the extension.
+.SS "Basic Constraints"
+.IX Subsection "Basic Constraints"
+This is a multi-valued extension which indicates whether a certificate is
+a \s-1CA\s0 certificate. The first value is \fB\s-1CA\s0\fR followed by \fB\s-1TRUE\s0\fR or
\&\fB\s-1FALSE\s0\fR. If \fB\s-1CA\s0\fR is \fB\s-1TRUE\s0\fR then an optional \fBpathlen\fR name followed by a
nonnegative value can be included.
.PP
For example:
.PP
.Vb 1
-\& basicConstraints=CA:TRUE
+\& basicConstraints = CA:TRUE
\&
-\& basicConstraints=CA:FALSE
+\& basicConstraints = CA:FALSE
\&
-\& basicConstraints=critical,CA:TRUE, pathlen:0
-.Ve
-.PP
-A \s-1CA\s0 certificate \fBmust\fR include the basicConstraints value with the \s-1CA\s0 field
-set to \s-1TRUE.\s0 An end user certificate must either set \s-1CA\s0 to \s-1FALSE\s0 or exclude the
-extension entirely. Some software may require the inclusion of basicConstraints
-with \s-1CA\s0 set to \s-1FALSE\s0 for end entity certificates.
-.PP
-The pathlen parameter indicates the maximum number of CAs that can appear
-below this one in a chain. So if you have a \s-1CA\s0 with a pathlen of zero it can
-only be used to sign end user certificates and not further CAs.
-.SS "Key Usage."
-.IX Subsection "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: digitalSignature, nonRepudiation, keyEncipherment,
-dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
-and decipherOnly.
+\& basicConstraints = critical, CA:TRUE, pathlen:1
+.Ve
+.PP
+A \s-1CA\s0 certificate \fImust\fR include the \fBbasicConstraints\fR name with the \fB\s-1CA\s0\fR
+parameter set to \fB\s-1TRUE\s0\fR. An end-user certificate must either have \fB\s-1CA:FALSE\s0\fR
+or omit the extension entirely.
+The \fBpathlen\fR parameter specifies the maximum number of CAs that can appear
+below this one in a chain. A \fBpathlen\fR of zero means the \s-1CA\s0 cannot sign
+any sub-CA's, and can only sign end-entity certificates.
+.SS "Key Usage"
+.IX Subsection "Key Usage"
+Key usage is a multi-valued extension consisting of a list of names of
+the permitted key usages. The defined values are: \f(CW\*(C`digitalSignature\*(C'\fR,
+\&\f(CW\*(C`nonRepudiation\*(C'\fR, \f(CW\*(C`keyEncipherment\*(C'\fR, \f(CW\*(C`dataEncipherment\*(C'\fR, \f(CW\*(C`keyAgreement\*(C'\fR,
+\&\f(CW\*(C`keyCertSign\*(C'\fR, \f(CW\*(C`cRLSign\*(C'\fR, \f(CW\*(C`encipherOnly\*(C'\fR, and \f(CW\*(C`decipherOnly\*(C'\fR.
.PP
Examples:
.PP
.Vb 1
-\& keyUsage=digitalSignature, nonRepudiation
+\& keyUsage = digitalSignature, nonRepudiation
\&
-\& keyUsage=critical, keyCertSign
+\& keyUsage = critical, keyCertSign
.Ve
-.SS "Extended Key Usage."
-.IX Subsection "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 \s-1OID\s0 can be used only certain values make sense. In particular the
-following \s-1PKIX, NS\s0 and \s-1MS\s0 values are meaningful:
+.SS "Extended Key Usage"
+.IX Subsection "Extended Key Usage"
+This extension consists of a list of values indicating purposes for which
+the certificate public key can be used.
+Each value can be either a short text name or an \s-1OID.\s0
+The following text names, and their intended meaning, are known:
.PP
.Vb 10
-\& Value Meaning
-\& \-\-\-\-\- \-\-\-\-\-\-\-
-\& serverAuth SSL/TLS Web Server Authentication.
-\& clientAuth SSL/TLS Web Client Authentication.
-\& codeSigning Code signing.
-\& emailProtection E\-mail Protection (S/MIME).
+\& Value Meaning according to RFC 5280 etc.
+\& \-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
+\& serverAuth SSL/TLS WWW Server Authentication
+\& clientAuth SSL/TLS WWW Client Authentication
+\& codeSigning Code Signing
+\& emailProtection E\-mail Protection (S/MIME)
\& timeStamping Trusted Timestamping
\& OCSPSigning OCSP Signing
\& ipsecIKE ipsec Internet Key Exchange
@@ -264,255 +312,311 @@ following \s-1PKIX, NS\s0 and \s-1MS\s0 values are meaningful:
\& msEFS Microsoft Encrypted File System
.Ve
.PP
-Examples:
+While \s-1IETF RFC 5280\s0 says that \fBid-kp-serverAuth\fR and \fBid-kp-clientAuth\fR
+are only for \s-1WWW\s0 use, in practice they are used for all kinds of \s-1TLS\s0 clients
+and servers, and this is what OpenSSL assumes as well.
.PP
-.Vb 2
-\& extendedKeyUsage=critical,codeSigning,1.2.3.4
-\& extendedKeyUsage=serverAuth,clientAuth
-.Ve
-.SS "Subject Key Identifier."
-.IX Subsection "Subject Key Identifier."
-This is really a string extension and can take two possible values. Either
-the word \fBhash\fR which will automatically follow the guidelines in \s-1RFC3280\s0
-or a hex string giving the extension value to include. The use of the hex
-string is strongly discouraged.
-.PP
-Example:
+Examples:
.PP
.Vb 1
-\& subjectKeyIdentifier=hash
+\& extendedKeyUsage = critical, codeSigning, 1.2.3.4
+\&
+\& extendedKeyUsage = serverAuth, clientAuth
.Ve
-.SS "Authority Key Identifier."
-.IX Subsection "Authority Key Identifier."
-The authority key identifier extension permits two options. keyid and issuer:
-both can take the optional value \*(L"always\*(R".
+.SS "Subject Key Identifier"
+.IX Subsection "Subject Key Identifier"
+The \s-1SKID\s0 extension specification has a value with three choices.
+If the value is the word \fBnone\fR then no \s-1SKID\s0 extension will be included.
+If the value is the word \fBhash\fR, or by default for the \fBx509\fR, \fBreq\fR, and
+\&\fBca\fR apps, the process specified in \s-1RFC 5280\s0 section 4.2.1.2. (1) is followed:
+The keyIdentifier is composed of the 160\-bit \s-1SHA\-1\s0 hash of the value of the \s-1BIT
+STRING\s0 subjectPublicKey (excluding the tag, length, and number of unused bits).
.PP
-If the keyid option is present an attempt is made to copy the subject key
-identifier from the parent certificate. If the value \*(L"always\*(R" is present
-then an error is returned if the option fails.
-.PP
-The issuer option copies the issuer and serial number from the issuer
-certificate. This will only be done if the keyid option fails or
-is not included unless the \*(L"always\*(R" flag will always include the value.
+Otherwise, the value must be a hex string (possibly with \f(CW\*(C`:\*(C'\fR separating bytes)
+to output directly, however, this is strongly discouraged.
.PP
Example:
.PP
.Vb 1
-\& authorityKeyIdentifier=keyid,issuer
-.Ve
-.SS "Subject Alternative Name."
-.IX Subsection "Subject Alternative Name."
-The subject alternative name extension allows various literal values to be
-included in the configuration file. These include \fBemail\fR (an email address)
-\&\fB\s-1URI\s0\fR a uniform resource indicator, \fB\s-1DNS\s0\fR (a \s-1DNS\s0 domain name), \fB\s-1RID\s0\fR (a
-registered \s-1ID: OBJECT IDENTIFIER\s0), \fB\s-1IP\s0\fR (an \s-1IP\s0 address), \fBdirName\fR
-(a distinguished name) and otherName.
+\& subjectKeyIdentifier = hash
+.Ve
+.SS "Authority Key Identifier"
+.IX Subsection "Authority Key Identifier"
+The \s-1AKID\s0 extension specification may have the value \fBnone\fR
+indicating that no \s-1AKID\s0 shall be included.
+Otherwise it may have the value \fBkeyid\fR or \fBissuer\fR
+or both of them, separated by \f(CW\*(C`,\*(C'\fR.
+Either or both can have the option \fBalways\fR,
+indicated by putting a colon \f(CW\*(C`:\*(C'\fR between the value and this option.
+For self-signed certificates the \s-1AKID\s0 is suppressed unless \fBalways\fR is present.
+By default the \fBx509\fR, \fBreq\fR, and \fBca\fR apps behave as if
+\&\*(L"none\*(R" was given for self-signed certificates and \*(L"keyid, issuer\*(R" otherwise.
+.PP
+If \fBkeyid\fR is present, an attempt is made to
+copy the subject key identifier (\s-1SKID\s0) from the issuer certificate except if
+the issuer certificate is the same as the current one and it is not self-signed.
+The hash of the public key related to the signing key is taken as fallback
+if the issuer certificate is the same as the current certificate.
+If \fBalways\fR is present but no value can be obtained, an error is returned.
+.PP
+If \fBissuer\fR is present, and in addition it has the option \fBalways\fR specified
+or \fBkeyid\fR is not present,
+then the issuer \s-1DN\s0 and serial number are copied from the issuer certificate.
.PP
-The email option include a special 'copy' value. This will automatically
-include any email addresses contained in the certificate subject name in
-the extension.
-.PP
-The \s-1IP\s0 address used in the \fB\s-1IP\s0\fR options can be in either IPv4 or IPv6 format.
-.PP
-The value of \fBdirName\fR 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 \fB+\fR character.
+Examples:
.PP
-otherName can include arbitrary data associated with an \s-1OID:\s0 the value
-should be the \s-1OID\s0 followed by a semicolon and the content in standard
-\&\fBASN1_generate_nconf\fR\|(3) format.
+.Vb 1
+\& authorityKeyIdentifier = keyid, issuer
+\&
+\& authorityKeyIdentifier = keyid, issuer:always
+.Ve
+.SS "Subject Alternative Name"
+.IX Subsection "Subject Alternative Name"
+This is a multi-valued extension that supports several types of name
+identifier, including
+\&\fBemail\fR (an email address),
+\&\fB\s-1URI\s0\fR (a uniform resource indicator),
+\&\fB\s-1DNS\s0\fR (a \s-1DNS\s0 domain name),
+\&\fB\s-1RID\s0\fR (a registered \s-1ID: OBJECT IDENTIFIER\s0),
+\&\fB\s-1IP\s0\fR (an \s-1IP\s0 address),
+\&\fBdirName\fR (a distinguished name),
+and \fBotherName\fR.
+The syntax of each is described in the following paragraphs.
+.PP
+The \fBemail\fR option has two special values.
+\&\f(CW\*(C`copy\*(C'\fR will automatically include any email addresses
+contained in the certificate subject name in the extension.
+\&\f(CW\*(C`move\*(C'\fR will automatically move any email addresses
+from the certificate subject name to the extension.
+.PP
+The \s-1IP\s0 address used in the \fB\s-1IP\s0\fR option can be in either IPv4 or IPv6 format.
+.PP
+The value of \fBdirName\fR is specifies the configuration section containing
+the distinguished name to use, as a set of name-value pairs.
+Multi-valued AVAs can be formed by prefacing the name with a \fB+\fR character.
+.PP
+The value of \fBotherName\fR can include arbitrary data associated with an \s-1OID\s0;
+the value should be the \s-1OID\s0 followed by a semicolon and the content in specified
+using the syntax in \fBASN1_generate_nconf\fR\|(3).
.PP
Examples:
.PP
-.Vb 5
-\& 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
+.Vb 1
+\& subjectAltName = email:copy, email:my@example.com, URI:http://my.example.com/
+\&
+\& subjectAltName = IP:192.168.7.1
+\&
+\& subjectAltName = IP:13::17
\&
-\& subjectAltName=dirName:dir_sect
+\& subjectAltName = email:my@example.com, RID:1.2.3.4
+\&
+\& subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
+\&
+\& [extensions]
+\& subjectAltName = dirName:dir_sect
\&
\& [dir_sect]
-\& C=UK
-\& O=My Organization
-\& OU=My Unit
-\& CN=My Name
-.Ve
-.SS "Issuer Alternative Name."
-.IX Subsection "Issuer Alternative Name."
-The issuer alternative name option supports all the literal options of
-subject alternative name. It does \fBnot\fR support the email:copy option because
-that would not make sense. It does support an additional issuer:copy option
-that will copy all the subject alternative name values from the issuer
-certificate (if possible).
+\& C = UK
+\& O = My Organization
+\& OU = My Unit
+\& CN = My Name
+.Ve
+.PP
+Non-ASCII Email Address conforming the syntax defined in Section 3.3 of \s-1RFC 6531\s0
+are provided as otherName.SmtpUTF8Mailbox. According to \s-1RFC 8398,\s0 the email
+address should be provided as UTF8String. To enforce the valid representation in
+the certificate, the SmtpUTF8Mailbox should be provided as follows
+.PP
+.Vb 3
+\& subjectAltName=@alts
+\& [alts]
+\& otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com
+.Ve
+.SS "Issuer Alternative Name"
+.IX Subsection "Issuer Alternative Name"
+This extension supports most of the options of subject alternative name;
+it does not support \fBemail:copy\fR.
+It also adds \fBissuer:copy\fR as an allowed value, which copies any subject
+alternative names from the issuer certificate, if possible.
.PP
Example:
.PP
.Vb 1
\& issuerAltName = issuer:copy
.Ve
-.SS "Authority Info Access."
-.IX Subsection "Authority Info Access."
-The authority information access extension gives details about how to access
-certain information relating to the \s-1CA.\s0 Its syntax is accessOID;location
-where \fIlocation\fR has the same syntax as subject alternative name (except
-that email:copy is not supported). accessOID can be any valid \s-1OID\s0 but only
-certain values are meaningful, for example \s-1OCSP\s0 and caIssuers.
+.SS "Authority Info Access"
+.IX Subsection "Authority Info Access"
+This extension gives details about how to retrieve information that
+related to the certificate that the \s-1CA\s0 makes available. The syntax is
+\&\fBaccess_id;location\fR, where \fBaccess_id\fR is an object identifier
+(although only a few values are well-known) and \fBlocation\fR has the same
+syntax as subject alternative name (except that \fBemail:copy\fR is not supported).
.PP
-Example:
+Possible values for access_id include \fB\s-1OCSP\s0\fR (\s-1OCSP\s0 responder),
+\&\fBcaIssuers\fR (\s-1CA\s0 Issuers),
+\&\fBad_timestamping\fR (\s-1AD\s0 Time Stamping),
+\&\fB\s-1AD_DVCS\s0\fR (ad dvcs),
+\&\fBcaRepository\fR (\s-1CA\s0 Repository).
.PP
-.Vb 2
-\& authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
-\& authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
+Examples:
+.PP
+.Vb 1
+\& authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer
+\&
+\& authorityInfoAccess = OCSP;URI:http://ocsp.example.com/
.Ve
.SS "\s-1CRL\s0 distribution points"
.IX Subsection "CRL distribution points"
-This is a multi-valued extension whose options can be either in name:value pair
-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 name: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 \*(L"fullname\*(R" 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 \*(L"relativename\*(R" then the value field should contain a section
-name whose contents represent a \s-1DN\s0 fragment to be placed in this field.
-.PP
-The name \*(L"CRLIssuer\*(R" if present should contain a value for this field in
-subject alternative name format.
-.PP
-If the name is \*(L"reasons\*(R" the value field should consist of a comma
-separated field containing the reasons. Valid reasons are: \*(L"keyCompromise\*(R",
-\&\*(L"CACompromise\*(R", \*(L"affiliationChanged\*(R", \*(L"superseded\*(R", \*(L"cessationOfOperation\*(R",
-\&\*(L"certificateHold\*(R", \*(L"privilegeWithdrawn\*(R" and \*(L"AACompromise\*(R".
+This is a multi-valued extension whose values can be either a name-value
+pair using the same form as subject alternative name or a single value
+specifying the section name containing all the distribution point values.
+.PP
+When a name-value pair is used, a DistributionPoint extension will
+be set with the given value as the fullName field as the distributionPoint
+value, and the reasons and cRLIssuer fields will be omitted.
+.PP
+When a single option is used, the value specifies the section, and that
+section can have the following items:
+.IP "fullname" 4
+.IX Item "fullname"
+The full name of the distribution point, in the same format as the subject
+alternative name.
+.IP "relativename" 4
+.IX Item "relativename"
+The value is taken as a distinguished name fragment that is set as the
+value of the nameRelativeToCRLIssuer field.
+.IP "CRLIssuer" 4
+.IX Item "CRLIssuer"
+The value must in the same format as the subject alternative name.
+.IP "reasons" 4
+.IX Item "reasons"
+A multi-value field that contains the reasons for revocation. The recognized
+values are: \f(CW\*(C`keyCompromise\*(C'\fR, \f(CW\*(C`CACompromise\*(C'\fR, \f(CW\*(C`affiliationChanged\*(C'\fR,
+\&\f(CW\*(C`superseded\*(C'\fR, \f(CW\*(C`cessationOfOperation\*(C'\fR, \f(CW\*(C`certificateHold\*(C'\fR,
+\&\f(CW\*(C`privilegeWithdrawn\*(C'\fR, and \f(CW\*(C`AACompromise\*(C'\fR.
+.PP
+Only one of \fBfullname\fR or \fBrelativename\fR should be specified.
.PP
Simple examples:
.PP
-.Vb 2
-\& crlDistributionPoints=URI:http://myhost.com/myca.crl
-\& crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
+.Vb 1
+\& crlDistributionPoints = URI:http://example.com/myca.crl
+\&
+\& crlDistributionPoints = URI:http://example.com/myca.crl, URI:http://example.org/my.crl
.Ve
.PP
Full distribution point example:
.PP
-.Vb 1
-\& crlDistributionPoints=crldp1_section
+.Vb 2
+\& [extensions]
+\& crlDistributionPoints = crldp1_section
\&
\& [crldp1_section]
-\&
-\& fullname=URI:http://myhost.com/myca.crl
-\& CRLissuer=dirName:issuer_sect
-\& reasons=keyCompromise, CACompromise
+\& fullname = URI:http://example.com/myca.crl
+\& CRLissuer = dirName:issuer_sect
+\& reasons = keyCompromise, CACompromise
\&
\& [issuer_sect]
-\& C=UK
-\& O=Organisation
-\& CN=Some Name
+\& C = UK
+\& O = Organisation
+\& CN = Some Name
.Ve
.SS "Issuing Distribution Point"
.IX Subsection "Issuing Distribution Point"
-This extension should only appear in CRLs. It is a multi valued extension
+This extension should only appear in CRLs. It is a multi-valued extension
whose syntax is similar to the \*(L"section\*(R" pointed to by the \s-1CRL\s0 distribution
-points extension with a few differences.
-.PP
-The names \*(L"reasons\*(R" and \*(L"CRLissuer\*(R" are not recognized.
-.PP
-The name \*(L"onlysomereasons\*(R" is accepted which sets this field. The value is
-in the same format as the \s-1CRL\s0 distribution point \*(L"reasons\*(R" field.
-.PP
-The names \*(L"onlyuser\*(R", \*(L"onlyCA\*(R", \*(L"onlyAA\*(R" and \*(L"indirectCRL\*(R" are also accepted
-the values should be a boolean value (\s-1TRUE\s0 or \s-1FALSE\s0) to indicate the value of
-the corresponding field.
+points extension. The following names have meaning:
+.IP "fullname" 4
+.IX Item "fullname"
+The full name of the distribution point, in the same format as the subject
+alternative name.
+.IP "relativename" 4
+.IX Item "relativename"
+The value is taken as a distinguished name fragment that is set as the
+value of the nameRelativeToCRLIssuer field.
+.IP "onlysomereasons" 4
+.IX Item "onlysomereasons"
+A multi-value field that contains the reasons for revocation. The recognized
+values are: \f(CW\*(C`keyCompromise\*(C'\fR, \f(CW\*(C`CACompromise\*(C'\fR, \f(CW\*(C`affiliationChanged\*(C'\fR,
+\&\f(CW\*(C`superseded\*(C'\fR, \f(CW\*(C`cessationOfOperation\*(C'\fR, \f(CW\*(C`certificateHold\*(C'\fR,
+\&\f(CW\*(C`privilegeWithdrawn\*(C'\fR, and \f(CW\*(C`AACompromise\*(C'\fR.
+.IP "onlyuser, onlyCA, onlyAA, indirectCRL" 4
+.IX Item "onlyuser, onlyCA, onlyAA, indirectCRL"
+The value for each of these names is a boolean.
.PP
Example:
.PP
-.Vb 1
-\& issuingDistributionPoint=critical, @idp_section
+.Vb 2
+\& [extensions]
+\& 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
+\& fullname = URI:http://example.com/myca.crl
+\& indirectCRL = TRUE
+\& onlysomereasons = keyCompromise, CACompromise
.Ve
-.SS "Certificate Policies."
-.IX Subsection "Certificate Policies."
-This is a \fIraw\fR extension. All the fields of this extension can be set by
-using the appropriate syntax.
+.SS "Certificate Policies"
+.IX Subsection "Certificate Policies"
+This is a \fIraw\fR extension that supports all of the defined fields of the
+certificate extension.
.PP
-If you follow the \s-1PKIX\s0 recommendations and just using one \s-1OID\s0 then you just
-include the value of that \s-1OID.\s0 Multiple OIDs can be set separated by commas,
-for example:
+Policies without qualifiers are specified by giving the \s-1OID.\s0
+Multiple policies are comma-separated. For example:
.PP
.Vb 1
-\& certificatePolicies= 1.2.4.5, 1.1.3.4
+\& certificatePolicies = 1.2.4.5, 1.1.3.4
.Ve
.PP
-If you wish to include qualifiers then the policy \s-1OID\s0 and qualifiers need to
-be specified in a separate section: this is done by using the \f(CW@section\fR syntax
-instead of a literal \s-1OID\s0 value.
+To include policy qualifiers, use the \*(L"@section\*(R" syntax to point to a
+section that specifies all the information.
.PP
The section referred to must include the policy \s-1OID\s0 using the name
-policyIdentifier, cPSuri qualifiers can be included using the syntax:
+\&\fBpolicyIdentifier\fR. cPSuri qualifiers can be included using the syntax:
.PP
.Vb 1
-\& CPS.nnn=value
+\& CPS.nnn = value
.Ve
.PP
+where \f(CW\*(C`nnn\*(C'\fR is a number.
+.PP
userNotice qualifiers can be set using the syntax:
.PP
.Vb 1
-\& userNotice.nnn=@notice
+\& userNotice.nnn = @notice
.Ve
.PP
The value of the userNotice qualifier is specified in the relevant section.
-This section can include explicitText, organization and noticeNumbers
+This section can include \fBexplicitText\fR, \fBorganization\fR, and \fBnoticeNumbers\fR
options. explicitText and organization are text strings, noticeNumbers is a
comma separated list of numbers. The organization and noticeNumbers options
-(if included) must \s-1BOTH\s0 be present. If you use the userNotice option with \s-1IE5\s0
-then you need the 'ia5org' option at the top level to modify the encoding:
-otherwise it will not be interpreted properly.
+(if included) must \s-1BOTH\s0 be present. Some software might require
+the \fBia5org\fR option at the top level; this changes the encoding from
+Displaytext to IA5String.
.PP
Example:
.PP
-.Vb 1
-\& certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
+.Vb 2
+\& [extensions]
+\& 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
+\& CPS.1 = "http://my.host.example.com/"
+\& CPS.2 = "http://my.your.example.com/"
+\& userNotice.1 = @notice
\&
\& [notice]
-\&
-\& explicitText="Explicit Text Here"
-\& organization="Organisation Name"
-\& noticeNumbers=1,2,3,4
+\& explicitText = "Explicit Text Here"
+\& organization = "Organisation Name"
+\& noticeNumbers = 1, 2, 3, 4
.Ve
.PP
-The \fBia5org\fR option changes the type of the \fIorganization\fR field. In \s-1RFC2459\s0
-it can only be of type DisplayText. In \s-1RFC3280\s0 IA5String is also permissible.
-Some software (for example some versions of \s-1MSIE\s0) may require ia5org.
-.PP
-\&\s-1ASN1\s0 type of explicitText can be specified by prepending \fB\s-1UTF8\s0\fR,
-\&\fB\s-1BMP\s0\fR or \fB\s-1VISIBLE\s0\fR prefix followed by colon. For example:
+The character encoding of explicitText can be specified by prefixing the
+value with \fB\s-1UTF8\s0\fR, \fB\s-1BMP\s0\fR, or \fB\s-1VISIBLE\s0\fR followed by colon. For example:
.PP
.Vb 2
\& [notice]
-\& explicitText="UTF8:Explicit Text Here"
+\& explicitText = "UTF8:Explicit Text Here"
.Ve
.SS "Policy Constraints"
.IX Subsection "Policy Constraints"
@@ -536,24 +640,25 @@ Example:
.Ve
.SS "Name Constraints"
.IX Subsection "Name Constraints"
-The name constraints extension is a multi-valued extension. The name should
+This is a multi-valued extension. The name should
begin with the word \fBpermitted\fR or \fBexcluded\fR followed by a \fB;\fR. The rest of
-the name and the value follows the syntax of subjectAltName except email:copy
+the name and the value follows the syntax of subjectAltName except
+\&\fBemail:copy\fR
is not supported and the \fB\s-1IP\s0\fR form should consist of an \s-1IP\s0 addresses and
subnet mask separated by a \fB/\fR.
.PP
Examples:
.PP
.Vb 1
-\& nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
+\& nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
\&
-\& nameConstraints=permitted;email:.somedomain.com
+\& nameConstraints = permitted;email:.example.com
\&
-\& nameConstraints=excluded;email:.com
+\& nameConstraints = excluded;email:.com
.Ve
.SS "\s-1OCSP\s0 No Check"
.IX Subsection "OCSP No Check"
-The \s-1OCSP\s0 No Check extension is a string extension but its value is ignored.
+This is a string extension. It is parsed, but ignored.
.PP
Example:
.PP
@@ -578,18 +683,11 @@ Example:
.IX Header "DEPRECATED EXTENSIONS"
The following extensions are non standard, Netscape specific and largely
obsolete. Their use in new applications is discouraged.
-.SS "Netscape String extensions."
-.IX Subsection "Netscape String extensions."
+.SS "Netscape String extensions"
+.IX Subsection "Netscape String extensions"
Netscape Comment (\fBnsComment\fR) is a string extension containing a comment
which will be displayed when the certificate is viewed in some browsers.
-.PP
-Example:
-.PP
-.Vb 1
-\& nsComment = "Some Random Comment"
-.Ve
-.PP
-Other supported extensions in this category are: \fBnsBaseUrl\fR,
+Other extensions of this type are: \fBnsBaseUrl\fR,
\&\fBnsRevocationUrl\fR, \fBnsCaRevocationUrl\fR, \fBnsRenewalUrl\fR, \fBnsCaPolicyUrl\fR
and \fBnsSslServerName\fR.
.SS "Netscape Certificate Type"
@@ -614,13 +712,12 @@ The first way is to use the word \s-1ASN1\s0 followed by the extension content
using the same syntax as \fBASN1_generate_nconf\fR\|(3).
For example:
.PP
-.Vb 1
-\& 1.2.3.4=critical,ASN1:UTF8String:Some random data
-\&
-\& 1.2.3.4=ASN1:SEQUENCE:seq_sect
+.Vb 3
+\& [extensions]
+\& 1.2.3.4 = critical, ASN1:UTF8String:Some random data
+\& 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
\&
\& [seq_sect]
-\&
\& field1 = UTF8:field1
\& field2 = UTF8:field2
.Ve
@@ -629,8 +726,8 @@ It is also possible to use the word \s-1DER\s0 to include the raw encoded data i
extension.
.PP
.Vb 2
-\& 1.2.3.4=critical,DER:01:02:03:04
-\& 1.2.3.4=DER:01020304
+\& 1.2.3.4 = critical, DER:01:02:03:04
+\& 1.2.3.4.1 = DER:01020304
.Ve
.PP
The value following \s-1DER\s0 is a hex dump of the \s-1DER\s0 encoding of the extension
@@ -638,7 +735,7 @@ Any extension can be placed in this form to override the default behaviour.
For example:
.PP
.Vb 1
-\& basicConstraints=critical,DER:00:01:02:03
+\& basicConstraints = critical, DER:00:01:02:03
.Ve
.SH "WARNINGS"
.IX Header "WARNINGS"
@@ -648,57 +745,16 @@ purposes prohibited by their extensions because a specific application does
not recognize or honour the values of the relevant extensions.
.PP
The \s-1DER\s0 and \s-1ASN1\s0 options should be used with caution. It is possible to create
-totally invalid extensions if they are not used carefully.
-.SH "NOTES"
-.IX Header "NOTES"
-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
-.Vb 1
-\& subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
-.Ve
-.PP
-will produce an error but the equivalent form:
-.PP
-.Vb 1
-\& subjectAltName=@subject_alt_section
-\&
-\& [subject_alt_section]
-\& subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
-.Ve
-.PP
-is valid.
-.PP
-Due to the behaviour of the OpenSSL \fBconf\fR library the same field name
-can only occur once in a section. This means that:
-.PP
-.Vb 1
-\& subjectAltName=@alt_section
-\&
-\& [alt_section]
-\&
-\& email=steve@here
-\& email=steve@there
-.Ve
-.PP
-will only recognize the last value. This can be worked around by using the form:
-.PP
-.Vb 1
-\& [alt_section]
-\&
-\& email.1=steve@here
-\& email.2=steve@there
-.Ve
+invalid extensions if they are not used carefully.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
-\&\fBreq\fR\|(1), \fBca\fR\|(1), \fBx509\fR\|(1),
+\&\fBopenssl\-req\fR\|(1), \fBopenssl\-ca\fR\|(1), \fBopenssl\-x509\fR\|(1),
\&\fBASN1_generate_nconf\fR\|(3)
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
-Copyright 2004\-2020 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2004\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
-Licensed under the OpenSSL license (the \*(L"License\*(R"). You may not use
+Licensed under the Apache License 2.0 (the \*(L"License\*(R"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file \s-1LICENSE\s0 in the source distribution or at
<https://www.openssl.org/source/license.html>.
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-29 06:00:32 +0000