diff options
Diffstat (limited to 'openssl/doc/apps/x509v3_config.pod')
| -rw-r--r-- | openssl/doc/apps/x509v3_config.pod | 529 |
1 files changed, 0 insertions, 529 deletions
diff --git a/openssl/doc/apps/x509v3_config.pod b/openssl/doc/apps/x509v3_config.pod deleted file mode 100644 index fb5f79c..0000000 --- a/openssl/doc/apps/x509v3_config.pod +++ /dev/null @@ -1,529 +0,0 @@ -=pod - -=for comment openssl_manual_section:5 - -=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<critical> is present then the extension will be critical. - -The format of B<extension_options> depends on the value of B<extension_name>. - -There are four main types of extension: I<string> extensions, I<multi-valued> -extensions, I<raw> and I<arbitrary> 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<arbitrary> extension syntax -must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> 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<CA> followed by B<TRUE> or -B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> 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<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. - - -=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 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: - - 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<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. - -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. This will only be done if the keyid option fails or -is not included unless the "always" flag will always include the value. - -Example: - - authorityKeyIdentifier=keyid,issuer - - -=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 -include and 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 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. - -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)|ASN1_generate_nconf(3)> format. - -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=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). - -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<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. - -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 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. - -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. - -In the single option case the section indicated contains values for each -field. In this section: - -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. - -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. - -The name "CRLIssuer" if present should contain a value for this field in -subject alternative name format. - -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". - - -Simple examples: - - 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 - - [crldp1_section] - - fullname=URI:http://myhost.com/myca.crl - CRLissuer=dirName:issuer_sect - reasons=keyCompromise, CACompromise - - [issuer_sect] - C=UK - O=Organisation - CN=Some Name - -=head2 Issuing Distribution Point - -This extension should only appear in CRLs. It is a multi valued extension -whose syntax is similar to the "section" pointed to by the CRL distribution -points extension with a few differences. - -The names "reasons" and "CRLissuer" are not recognized. - -The name "onlysomereasons" is accepted which sets this field. The value is -in the same format as the CRL distribution point "reasons" field. - -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. - -Example: - - 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 - - -=head2 Certificate Policies. - -This is a I<raw> 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<ia5org> option changes the type of the I<organization> 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. - -=head2 Policy Constraints - -This is a multi-valued extension which consisting of the names -B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger -value. At least one component must be present. - -Example: - - policyConstraints = requireExplicitPolicy:3 - - -=head2 Inhibit Any Policy - -This is a string extension whose value must be a non negative integer. - -Example: - - inhibitAnyPolicy = 2 - - -=head2 Name Constraints - -The name constraints extension 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 -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=excluded;email:.com - - -=head2 OCSP No Check - -The OCSP No Check extension is a string extension but its value is ignored. - -Example: - - noCheck = ignored - - -=head1 DEPRECATED EXTENSIONS - -The following extensions are non standard, Netscape specific and largely -obsolete. Their use in new applications is discouraged. - -=head2 Netscape String extensions. - -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>, -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 -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<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 -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 L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>. -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<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 - -=head1 HISTORY - -The X509v3 extension code was first added to OpenSSL 0.9.2. - -Policy mappings, inhibit any policy and name constraints support was added in -OpenSSL 0.9.8 - -The B<directoryName> and B<otherName> option as well as the B<ASN1> option -for arbitrary extensions was added in OpenSSL 0.9.8 - -=head1 SEE ALSO - -L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>, -L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> - - -=cut |