Revise x509v3_config.pod
authorRich Salz <rsalz@akamai.com>
Fri, 20 Mar 2020 01:53:11 +0000 (21:53 -0400)
committerTomas Mraz <tmraz@fedoraproject.org>
Tue, 19 May 2020 14:05:56 +0000 (16:05 +0200)
Reviewed-by: Richard Levitte <levitte@openssl.org>
Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/11369)

doc/man5/x509v3_config.pod

index 2d37573..88a336c 100644 (file)
@@ -6,112 +6,148 @@ x509v3_config - X509 V3 certificate extension configuration format
 
 =head1 DESCRIPTION
 
-Several of the OpenSSL utilities can add extensions to a certificate or
+Several OpenSSL commands can add extensions to a certificate or
 certificate request based on the contents of a configuration file.
+The syntax of this file is described in L<config(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.
 
-Typically the application will contain an option to point to an extension
-section. Each line of the extension section takes the form:
+This page uses B<extensions> as the name of the section, when needed
+in examples.
 
- extension_name=[critical,] extension_options
+Each entry in the extension section takes the form:
 
-If B<critical> is present then the extension will be critical.
+ name = [critical, ]value(s)
 
-The format of B<extension_options> depends on the value of B<extension_name>.
+If B<critical> is present then the extension will be marked as critical.
 
-There are four main types of extension: I<string> extensions, I<multi-valued>
-extensions, I<raw> and I<arbitrary> extensions.
+The format of B<values> depends on the value of B<name>, many have a
+type-value pairing where the type and value are separated by a colon.
+There are four main types of extension:
 
-String extensions simply have a string which contains either the value itself
-or how it is obtained.
+ string
+ multi-valued
+ raw
+ arbitrary
 
-For example:
+Each is described in the following paragraphs.
 
- nsComment="This is a Comment"
+String extensions simply have a string which contains either the value itself
+or how it is obtained.
 
 Multi-valued extensions have a short form and a long form. The short form
-is a list of names and values:
+is a commma-separated list of names and values:
 
- basicConstraints=critical,CA:true,pathlen:1
+ basicConstraints = critical, CA:true, pathlen:1
 
 The long form allows the values to be placed in a separate section:
 
- basicConstraints=critical,@bs_section
-
- [bs_section]
+ [extensions]
+ basicConstraints = critical, @basic_constraints
 
- CA=true
- pathlen=1
+ [basic_constraints]
+ CA = true
+ pathlen = 1
 
 Both forms are equivalent.
 
-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.
+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:
+
+ subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
+
+will produce an error but the equivalent form:
+
+ [extensions]
+ subjectAltName = @subject_alt_section
+
+ [subject_alt_section]
+ subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
+
+is valid.
+
+OpenSSL does not support multiple occurences of the same field within a
+section. In this example:
+
+ [extensions]
+ subjectAltName = @alt_section
+
+ [alt_section]
+ email = steve@here
+ email = steve@there
+
+will only recognize the last value.  To specify multiple values append a
+numeric identifier, as shown here:
+
+ [extensions]
+ subjectAltName = @alt_section
+
+ [alt_section]
+ email.1 = steve@here
+ email.2 = steve@there
+
+The syntax of raw extensions is defined by the source code that parses
+the extension but should be documened.
+See L</Certificate Policies> for an example of a raw extension.
 
-If an extension type is unsupported then the I<arbitrary> extension syntax
+If an extension type is unsupported, then the I<arbitrary> extension syntax
 must be used, see the L</ARBITRARY EXTENSIONS> section for more details.
 
 =head1 STANDARD EXTENSIONS
 
-The following sections describe each supported extension in detail.
+The following sections describe the syntax of each supported extension.
+They do not define the semantics of the extension.
 
 =head2 Basic Constraints
 
-This is a multi valued extension which indicates whether a certificate is
-a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
+This is a multi-valued extension which indicates whether a certificate is
+a CA certificate. The first value is B<CA> followed by B<TRUE> or
 B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a
 non-negative value can be included.
 
 For example:
 
- basicConstraints=CA:TRUE
+ basicConstraints = CA:TRUE
 
- basicConstraints=CA:FALSE
+ basicConstraints = CA:FALSE
 
- basicConstraints=critical,CA:TRUE, pathlen:0
-
-A CA certificate B<must> include the basicConstraints value with the CA field
-set to TRUE. An end user certificate must either set CA to FALSE or exclude the
-extension entirely. Some software may require the inclusion of basicConstraints
-with CA set to FALSE for end entity certificates.
-
-The 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 pathlen of zero it can
-only be used to sign end user certificates and not further CAs.
+ basicConstraints = critical, CA:TRUE, pathlen:1
 
+A CA certificate I<must> include the B<basicConstraints> name with the B<CA>
+parameter set to B<TRUE>. An end-user certificate must either have B<CA:FALSE>
+or omit the extension entirely.
+The B<pathlen> parameter specifies the maximum number of CAs that can appear
+below this one in a chain. A B<pathlen> of zero means the CA cannot sign
+any sub-CA's, and can only sign end-entity certificates.
 
 =head2 Key Usage
 
-Key usage is a multi valued extension consisting of a list of names of the
-permitted key usages.
-
-The supported names are: digitalSignature, nonRepudiation, keyEncipherment,
-dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
-and decipherOnly.
+Key usage is a multi-valued extension consisting of a list of names of
+the permitted key usages.  The defined values are: C<digitalSignature>,
+C<nonRepudiation>, C<keyEncipherment>, C<dataEncipherment>, C<keyAgreement>,
+C<keyCertSign>, C<cRLSign>, C<encipherOnly>, and C<decipherOnly>.
 
 Examples:
 
- keyUsage=digitalSignature, nonRepudiation
-
- keyUsage=critical, keyCertSign
+ keyUsage = digitalSignature, nonRepudiation
 
+ keyUsage = critical, keyCertSign
 
 =head2 Extended Key Usage
 
-This extensions consists of a list of usages indicating purposes for which
-the certificate public key can be used for,
-
-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:
+This extension consists of a list of values indicating purposes for which
+the certificate public key can be used for, Each value can be either a
+short text name or an OID.
+The following text names, and their intended meaning, are known:
 
  Value                  Meaning
  -----                  -------
- serverAuth             SSL/TLS Web Server Authentication.
- clientAuth             SSL/TLS Web Client Authentication.
- codeSigning            Code signing.
- emailProtection        E-mail Protection (S/MIME).
+ serverAuth             SSL/TLS Web Server Authentication
+ clientAuth             SSL/TLS Web Client Authentication
+ codeSigning            Code signing
+ emailProtection        E-mail Protection (S/MIME)
  timeStamping           Trusted Timestamping
  OCSPSigning            OCSP Signing
  ipsecIKE               ipsec Internet Key Exchange
@@ -122,242 +158,267 @@ following PKIX, NS and MS values are meaningful:
 
 Examples:
 
- extendedKeyUsage=critical,codeSigning,1.2.3.4
- extendedKeyUsage=serverAuth,clientAuth
+ extendedKeyUsage = critical, codeSigning, 1.2.3.4
 
+ extendedKeyUsage = serverAuth, clientAuth
 
 =head2 Subject Key Identifier
 
-This is really a string extension and can take two possible values. Either
-the word B<hash> which will automatically follow the guidelines in RFC3280
-or a hex string giving the extension value to include. The use of the hex
-string is strongly discouraged.
+This is a string extension with one of two legal values. If it is the word
+B<hash>, then OpenSSL will follow the process in RFC 5280 to calculate the
+hash value.
+Otherwise, the value should be a hex string to output directly, however this
+is strongly discouraged.
 
 Example:
 
- subjectKeyIdentifier=hash
-
+ subjectKeyIdentifier = hash
 
 =head2 Authority Key Identifier
 
-The authority key identifier extension permits two options. keyid and issuer:
-both can take the optional value "always".
-
-If the keyid option is present an attempt is made to copy the subject key
-identifier from the parent certificate. If the value "always" is present
-then an error is returned if the option fails.
+This extension has two options, B<keyid> and B<issuer>. Either or both
+can have the value B<always>, indicated by putting a colon between
+the option and its value.
 
-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 "always" flag will always include the value.
+If B<keyid> is present, than an attempt is made to copy the subject key
+identifier from the parent certificate. If the value B<always> is present,
+then an error can be returned if the option fails.  If B<issuer> is present,
+an attempt is made to copy the issuer and serial number from the parent
+certificate. This is done if the B<keyid> option fails, or if B<issuer>
+has B<always> specified.
 
-Example:
+Examples:
 
- authorityKeyIdentifier=keyid,issuer
+ authorityKeyIdentifier = keyid, issuer
 
+ authorityKeyIdentifier = keyid, issuer:always
 
 =head2 Subject Alternative Name
 
-The subject alternative name extension allows various literal values to be
-included in the configuration file. These include B<email> (an email address)
-B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
-registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
-(a distinguished name) and otherName.
-
-The email option include a special 'copy' value. This will automatically
+This is a multi-valued extension that supports several types of name
+identifier, including
+B<email> (an email address),
+B<URI> (a uniform resource indicator),
+B<DNS> (a DNS domain name),
+B<RID> (a registered ID: OBJECT IDENTIFIER),
+B<IP> (an IP address),
+B<dirName> (a distinguished name),
+and B<otherName>.
+The syntax of each is described in the following paragraphs.
+
+The B<email> option has a special C<copy> value, which will automatically
 include any email addresses contained in the certificate subject name in
 the extension.
 
-The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
+The IP address used in the B<IP> option can be in either IPv4 or IPv6 format.
 
-The value of B<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 B<+> character.
+The value of B<dirName> 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 B<+> character.
 
-otherName can include arbitrary data associated with an OID: the value
-should be the OID followed by a semicolon and the content in standard
-L<ASN1_generate_nconf(3)> format.
+The value of B<otherName> can include arbitrary data associated with an OID;
+the value should be the OID followed by a semicolon and the content in specified
+using the syntax in L<ASN1_generate_nconf(3)>.
 
 Examples:
 
- 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 = email:copy, email:my@other.address, URI:http://my.url.here/
 
- subjectAltName=dirName:dir_sect
+ subjectAltName = IP:192.168.7.1
 
- [dir_sect]
- C=UK
- O=My Organization
- OU=My Unit
- CN=My Name
+ subjectAltName = IP:13::17
+
+ subjectAltName = email:my@other.address, 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
 
 =head2 Issuer Alternative Name
 
-The issuer alternative name option supports all the literal options of
-subject alternative name. It does B<not> 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).
+This extension supports most of the options of subject alternative name;
+it does not support B<email:copy>.
+It also adds B<issuer:copy> as an allowed value, which copies any subject
+alternative names from the issuer certificate, if possible.
 
 Example:
 
  issuerAltName = issuer:copy
 
-
 =head2 Authority Info Access
 
-The authority information access extension gives details about how to access
-certain information relating to the CA. Its syntax is accessOID;location
-where I<location> has the same syntax as subject alternative name (except
-that email:copy is not supported). accessOID can be any valid OID but only
-certain values are meaningful, for example OCSP and caIssuers.
+This extension gives details about how to retrieve information that
+related to the certificate that the CA makes available. The syntax is
+B<access_id;location>, where B<access_id> is an object identifier
+(although only a few values are well-known) and B<location> has the same
+syntax as subject alternative name (except that B<email:copy> is not supported).
 
-Example:
+Examples:
 
  authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
- authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
-
 
 =head2 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.
+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.
+
+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.
+
+When a single option is used, the value specifies the section, and that
+section can have the following items:
+
+=over 4
+
+=item fullname
+
+The full name of the distribution point, in the same format as the subject
+alternative name.
+
+=item relativename
 
-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.
+The value is taken as a distinguished name fragment that is set as the
+value of the nameRelativeToCRLIssuer field.
 
-In the single option case the section indicated contains values for each
-field. In this section:
+=item CRLIssuer
 
-If the name is "fullname" the value field should contain the full name
-of the distribution point in the same format as subject alternative name.
+The value must in the same format as the subject alternative name.
 
-If the name is "relativename" then the value field should contain a section
-name whose contents represent a DN fragment to be placed in this field.
+=item reasons
 
-The name "CRLIssuer" if present should contain a value for this field in
-subject alternative name format.
+A multi-value field that contains the reasons for revocation. The recognized
+values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
+C<superseded>, C<cessationOfOperation>, C<certificateHold>,
+C<privilegeWithdrawn>, and C<AACompromise>.
 
-If the name is "reasons" the value field should consist of a comma
-separated field containing the reasons. Valid reasons are: "keyCompromise",
-"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
-"certificateHold", "privilegeWithdrawn" and "AACompromise".
+=back
 
+Only one of B<fullname> or B<relativename> should be specified.
 
 Simple examples:
 
- crlDistributionPoints=URI:http://myhost.com/myca.crl
- crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
+ crlDistributionPoints = URI:http://myhost.com/myca.crl
+
+ crlDistributionPoints = URI:http://my.com/my.crl, URI:http://oth.com/my.crl
 
 Full distribution point example:
 
- crlDistributionPoints=crldp1_section
+ [extensions]
+ crlDistributionPoints = crldp1_section
 
  [crldp1_section]
-
- fullname=URI:http://myhost.com/myca.crl
- CRLissuer=dirName:issuer_sect
- reasons=keyCompromise, CACompromise
+ fullname = URI:http://myhost.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
 
 =head2 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 "section" pointed to by the CRL distribution
-points extension with a few differences.
+points extension. The following names have meaning:
 
-The names "reasons" and "CRLissuer" are not recognized.
+=over 4
 
-The name "onlysomereasons" is accepted which sets this field. The value is
-in the same format as the CRL distribution point "reasons" field.
+=item fullname
 
-The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
-the values should be a boolean value (TRUE or FALSE) to indicate the value of
-the corresponding field.
+The full name of the distribution point, in the same format as the subject
+alternative name.
 
-Example:
+=item relativename
 
- issuingDistributionPoint=critical, @idp_section
+The value is taken as a distinguished name fragment that is set as the
+value of the nameRelativeToCRLIssuer field.
 
- [idp_section]
+=item onlysomereasons
 
- fullname=URI:http://myhost.com/myca.crl
- indirectCRL=TRUE
- onlysomereasons=keyCompromise, CACompromise
+A multi-value field that contains the reasons for revocation. The recognized
+values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
+C<superseded>, C<cessationOfOperation>, C<certificateHold>,
+C<privilegeWithdrawn>, and C<AACompromise>.
 
- [issuer_sect]
- C=UK
- O=Organisation
- CN=Some Name
+=item onlyuser, onlyCA, onlyAA, indirectCRL
+
+The value for each of these names is a boolean.
 
+=back
+
+Example:
+
+ [extensions]
+ issuingDistributionPoint = critical, @idp_section
+
+ [idp_section]
+ fullname = URI:http://myhost.com/myca.crl
+ indirectCRL = TRUE
+ onlysomereasons = keyCompromise, CACompromise
 
 =head2 Certificate Policies
 
-This is a I<raw> extension. All the fields of this extension can be set by
-using the appropriate syntax.
+This is a I<raw> extension that supports all of the defined fields of the
+certificate extension.
 
-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:
+Policies without qualifiers are specified by giving the OID.
+Multiple policies are comma-separated. For example:
 
- certificatePolicies= 1.2.4.5, 1.1.3.4
+ certificatePolicies = 1.2.4.5, 1.1.3.4
 
-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 @section syntax
-instead of a literal OID value.
+To include policy qualifiers, use the "@section" syntax to point to a
+section that specifies all the information.
 
 The section referred to must include the policy OID using the name
-policyIdentifier, cPSuri qualifiers can be included using the syntax:
+B<policyIdentifier>. cPSuri qualifiers can be included using the syntax:
+
+ CPS.nnn = value
 
- CPS.nnn=value
+where C<nnn> is a number.
 
 userNotice qualifiers can be set using the syntax:
 
- userNotice.nnn=@notice
+ userNotice.nnn = @notice
 
 The value of the userNotice qualifier is specified in the relevant section.
-This section can include explicitText, organization and noticeNumbers
+This section can include B<explicitText>, B<organization>, and B<noticeNumbers>
 options. explicitText and organization are text strings, noticeNumbers is a
 comma separated list of numbers. The organization and noticeNumbers options
-(if included) must BOTH be present. If you use the userNotice option with IE5
-then you need the 'ia5org' option at the top level to modify the encoding:
-otherwise it will not be interpreted properly.
+(if included) must BOTH be present. Some software might require
+the B<ia5org> option at the top level; this changes the encoding from
+Displaytext to IA5String.
 
 Example:
 
- certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
+ [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.name/"
+ CPS.2 = "http://my.your.name/"
+ 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
-
-The B<ia5org> option changes the type of the I<organization> field. In RFC2459
-it can only be of type DisplayText. In RFC3280 IA5String is also permissible.
-Some software (for example some versions of MSIE) may require ia5org.
-
-ASN1 type of explicitText can be specified by prepending B<UTF8>,
-B<BMP> or B<VISIBLE> prefix followed by colon. For example:
+The character encoding of explicitText can be specified by prefixing the
+value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example:
 
  [notice]
- explicitText="UTF8:Explicit Text Here"
+ explicitText = "UTF8:Explicit Text Here"
 
 =head2 Policy Constraints
 
@@ -369,7 +430,6 @@ Example:
 
  policyConstraints = requireExplicitPolicy:3
 
-
 =head2 Inhibit Any Policy
 
 This is a string extension whose value must be a non negative integer.
@@ -378,33 +438,31 @@ Example:
 
  inhibitAnyPolicy = 2
 
-
 =head2 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 B<permitted> or B<excluded> followed by a B<;>. 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
+B<email:copy>
 is not supported and the B<IP> form should consist of an IP addresses and
 subnet mask separated by a B</>.
 
 Examples:
 
- nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
-
- nameConstraints=permitted;email:.somedomain.com
+ nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
 
- nameConstraints=excluded;email:.com
+ nameConstraints = permitted;email:.somedomain.com
 
+ nameConstraints = excluded;email:.com
 
 =head2 OCSP No Check
 
-The OCSP No Check extension is a string extension but its value is ignored.
+This is a string extension. It is parsed, but ignored.
 
 Example:
 
  noCheck = ignored
 
-
 =head2 TLS Feature (aka Must Staple)
 
 This is a multi-valued extension consisting of a list of TLS extension
@@ -418,7 +476,6 @@ Example:
 
  tlsfeature = status_request
 
-
 =head1 DEPRECATED EXTENSIONS
 
 The following extensions are non standard, Netscape specific and largely
@@ -428,16 +485,10 @@ obsolete. Their use in new applications is discouraged.
 
 Netscape Comment (B<nsComment>) is a string extension containing a comment
 which will be displayed when the certificate is viewed in some browsers.
-
-Example:
-
- nsComment = "Some Random Comment"
-
-Other supported extensions in this category are: B<nsBaseUrl>,
+Other extensions of this type are: B<nsBaseUrl>,
 B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
 and B<nsSslServerName>.
 
-
 =head2 Netscape Certificate Type
 
 This is a multi-valued extensions which consists of a list of flags to be
@@ -448,7 +499,6 @@ now used instead.
 Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
 B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
 
-
 =head1 ARBITRARY EXTENSIONS
 
 If an extension is not supported by the OpenSSL code then it must be encoded
@@ -462,26 +512,25 @@ The first way is to use the word ASN1 followed by the extension content
 using the same syntax as L<ASN1_generate_nconf(3)>.
 For example:
 
- 1.2.3.4=critical,ASN1:UTF8String:Some random data
-
- 1.2.3.4=ASN1:SEQUENCE:seq_sect
+ [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
 
 It is also possible to use the word DER to include the raw encoded data in any
 extension.
 
- 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
 
 The value following 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:
 
- basicConstraints=critical,DER:00:01:02:03
+ basicConstraints = critical, DER:00:01:02:03
 
 =head1 WARNINGS
 
@@ -491,41 +540,7 @@ purposes prohibited by their extensions because a specific application does
 not recognize or honour the values of the relevant extensions.
 
 The DER and ASN1 options should be used with caution. It is possible to create
-totally invalid extensions if they are not used carefully.
-
-=head1 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:
-
- subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
-
-will produce an error but the equivalent form:
-
- subjectAltName=@subject_alt_section
-
- [subject_alt_section]
- subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
-
-is valid.
-
-Due to the behaviour of the OpenSSL B<conf> library the same field name
-can only occur once in a section. This means that:
-
- subjectAltName=@alt_section
-
- [alt_section]
-
- email=steve@here
- email=steve@there
-
-will only recognize the last value. This can be worked around by using the form:
-
- [alt_section]
-
- email.1=steve@here
- email.2=steve@there
+invalid extensions if they are not used carefully.
 
 =head1 SEE ALSO