From eaf8ec1a03c5a034f43208d055b72d771ad134c3 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 19 Mar 2020 21:53:11 -0400 Subject: [PATCH] Revise x509v3_config.pod Reviewed-by: Richard Levitte Reviewed-by: Tomas Mraz (Merged from https://github.com/openssl/openssl/pull/11369) --- doc/man5/x509v3_config.pod | 523 +++++++++++++++++++------------------ 1 file changed, 269 insertions(+), 254 deletions(-) diff --git a/doc/man5/x509v3_config.pod b/doc/man5/x509v3_config.pod index 2d37573504..88a336c3b4 100644 --- a/doc/man5/x509v3_config.pod +++ b/doc/man5/x509v3_config.pod @@ -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. +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 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 is present then the extension will be critical. + name = [critical, ]value(s) -The format of B depends on the value of B. +If B is present then the extension will be marked as critical. -There are four main types of extension: I extensions, I -extensions, I and I extensions. +The format of B depends on the value of B, 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 for an example of a raw extension. -If an extension type is unsupported then the I extension syntax +If an extension type is unsupported, then the I extension syntax must be used, see the L 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 followed by B or +This is a multi-valued extension which indicates whether a certificate is +a CA certificate. The first value is B followed by B or B. If B is B then an optional B 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 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 include the B name with the B +parameter set to B. An end-user certificate must either have B +or omit the extension entirely. +The B parameter specifies the maximum number of CAs that can appear +below this one in a chain. A B 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, +C, C, C, C, +C, C, C, and C. 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 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, 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 and B. Either or both +can have the value B, 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 is present, than an attempt is made to copy the subject key +identifier from the parent certificate. If the value B is present, +then an error can be returned if the option fails. If B is present, +an attempt is made to copy the issuer and serial number from the parent +certificate. This is done if the B option fails, or if B +has B 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 (an email address) -B a uniform resource indicator, B (a DNS domain name), B (a -registered ID: OBJECT IDENTIFIER), B (an IP address), B -(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 (an email address), +B (a uniform resource indicator), +B (a DNS domain name), +B (a registered ID: OBJECT IDENTIFIER), +B (an IP address), +B (a distinguished name), +and B. +The syntax of each is described in the following paragraphs. + +The B option has a special C value, which will automatically include any email addresses contained in the certificate subject name in the extension. -The IP address used in the B options can be in either IPv4 or IPv6 format. +The IP address used in the B option can be in either IPv4 or IPv6 format. -The value of B 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 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 format. +The value of B 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. 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 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. +It also adds B 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 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, where B is an object identifier +(although only a few values are well-known) and B has the same +syntax as subject alternative name (except that B 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, C, C, +C, C, C, +C, and C. -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 or B 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, C, C, +C, C, C, +C, and C. - [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 extension. All the fields of this extension can be set by -using the appropriate syntax. +This is a I 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. cPSuri qualifiers can be included using the syntax: + + CPS.nnn = value - CPS.nnn=value +where C 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, B, and B 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 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 option changes the type of the I 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, -B or B prefix followed by colon. For example: +The character encoding of explicitText can be specified by prefixing the +value with B, B, or B 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 or B 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 is not supported and the B 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) 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, +Other extensions of this type are: B, B, B, B, B and B. - =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, B, B, B, B, B, B, B. - =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. 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 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 -- 2.25.1