diff --git a/doc/apps/x509v3_config.pod b/doc/apps/x509v3_config.pod new file mode 100644 index 0000000000000000000000000000000000000000..b19f52136cbd74b6d7987bfe9b004efec06d7a4c --- /dev/null +++ b/doc/apps/x509v3_config.pod @@ -0,0 +1,394 @@ +=pod + +=head1 NAME + +x509v3_config - X509 V3 certificate extension configuration format + +=head1 DESCRIPTION + +Several of the OpenSSL utilities can add extensions to a certificate or +certificate request based on the contents of a configuration file. + +Typically the application will contain an option to point to an extension +section. Each line of the extension section takes the form: + + extension_name=[critical,] extension_options + +If B is present then the extension will be critical. + +The format of B depends on the value of B. + +There are four main types of extension: I extensions, I +extensions, I and I extensions. + +String extensions simply have a string which contains either the value itself +or how it is obtained. + +For example: + + nsComment="This is a Comment" + +Multi-valued extensions have a short form and a long form. The short form +is a list of names and values: + + 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] + + 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 type is unsupported then the I extension syntax +must be used, see the ARBITRARY EXTENSION section for more details. + +=head1 STANDARD EXTENSIONS + +The following sections describe each supported extension in detail. + +=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 +B. If B is B then an optional B name followed by an +non-negative value can be included. + +For example: + + basicConstraints=CA:TRUE + + 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. + + +=head2 Key Usage. + +Key usage is a multi valued extension consisting of a list of names of the +permitted key usages. + +The supporte names are: digitalSignature, nonRepudiation, keyEncipherment, +dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly +and decipherOnly. + +Examples: + + 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 of 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: + + Value Meaning + ----- ------- + serverAuth SSL/TLS Web Server Authentication. + clientAuth SSL/TLS Web Client Authentication. + codeSigning Code signing. + emailProtection E-mail Protection (S/MIME). + timeStamping Trusted Timestamping + msCodeInd Microsoft Individual Code Signing (authenticode) + msCodeCom Microsoft Commercial Code Signing (authenticode) + msCTLSign Microsoft Trust List Signing + msSGC Microsoft Server Gated Crypto + msEFS Microsoft Encrypted File System + nsSGC Netscape Server Gated Crypto + +Examples: + + extendedKeyUsage=critical,codeSigning,1.2.3.4 + extendedKeyUsage=nsSGC,msSGC + + +=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. + +Example: + + 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. + +The issuer option copies the issuer and serial number from the issuer +certificate. Normally this will only be done if the keyid option fails or +is not included: the "always" flag will always include the value. + + +=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 +include and email addresses contained in the certificate subject name in +the extension. + +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 +preceeding 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 +ASN1_generate_nconf() format. + +Examples: + + subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ + subjectAltName=email:my@other.address,RID:1.2.3.4 + subjectAltName=otherName:1.2.3.4;UTF8:some other identifier + + subjectAltName=dirName:dir_sect + + [dir_sect] + C=UK + O=My Organization + OU=My Unit + CN=My Name + + +=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). + +Example: + + issuserAltName = 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. + +Example: + + 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 that supports all the literal options of +subject alternative name. Of the few software packages that currently interpret +this extension most only interpret the URI option. + +Currently each option will set a new DistributionPoint with the fullName +field set to the given value. + +Other fields like cRLissuer and reasons cannot currently be set or displayed: +at this time no examples were available that used these fields. + +Examples: + + crlDistributionPoints=URI:http://myhost.com/myca.crl + crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl + +=head2 Certificate Policies. + +This is a B extension. All the fields of this extension can be set by +using the appropriate syntax. + +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: + + 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. + +The section referred to must include the policy OID using the name +policyIdentifier, cPSuri qualifiers can be included using the syntax: + + CPS.nnn=value + +userNotice qualifiers can be set using the syntax: + + userNotice.nnn=@notice + +The value of the userNotice qualifier is specified in the relevant section. +This section can include explicitText, organization and 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. + +Example: + + certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect + + [polsect] + + policyIdentifier = 1.3.5.8 + CPS.1="http://my.host.name/" + CPS.2="http://my.your.name/" + userNotice.1=@notice + + [notice] + + explicitText="Explicit Text Here" + organization="Organisation Name" + noticeNumbers=1,2,3,4 + +The B option changes the type of the I field. In RFC2459 +it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible. +Some software (for example some versions of MSIE) may require ia5org. + + +=head1 DEPRECATED EXTENSIONS + +The following extensions are considered non standard, Netscape specific and +largely obsolete. Their use in new applications is discouraged. + +=head2 Netscape String extensions. + +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, +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 +included. It was used to indicate the purposes for which a certificate could +be used. The basicConstraints, keyUsage and extended key usage extensions are +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 +using the arbitrary extension format. It is also possible to use the arbitrary +format for supported extensions. Extreme care should be taken to ensure that +the data is formatted correctly for the given extension type. + +There are two ways to encode arbitrary extensions. + +The first way is to use the word ASN1 followed by the extension content +using the same syntax as ASN1_generate_nconf(). For example: + + 1.2.3.4=critical,ASN1:UTF8String:Some random data + + 1.2.3.4=ASN1:SEQUENCE:seq_sect + + [seq_sect] + + field1 = UTF8:field1 + field2 = UTF8:field2 + +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 + +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 + +=head1 WARNING + +There is no guarantee that a specific implementation will process a given +extension. It may therefore be sometimes possible to use certificates for +purposes prohibited by their extensions because a specific application does +not recognize or honour the values of the relevant extensions. + +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