Correct PPTP server firewall rules chain.
[tomato/davidwu.git] / release / src / router / openssl / doc / apps / x509v3_config.pod
blobc82cea1da24ee4f9a5708a3cb9d60c13c3e78e52
1 =pod
3 =for comment openssl_manual_section:5
5 =head1 NAME
7 x509v3_config - X509 V3 certificate extension configuration format
9 =head1 DESCRIPTION
11 Several of the OpenSSL utilities can add extensions to a certificate or
12 certificate request based on the contents of a configuration file.
14 Typically the application will contain an option to point to an extension
15 section. Each line of the extension section takes the form:
17  extension_name=[critical,] extension_options
19 If B<critical> is present then the extension will be critical.
21 The format of B<extension_options> depends on the value of B<extension_name>.
23 There are four main types of extension: I<string> extensions, I<multi-valued>
24 extensions, I<raw> and I<arbitrary> extensions.
26 String extensions simply have a string which contains either the value itself
27 or how it is obtained.
29 For example:
31  nsComment="This is a Comment"
33 Multi-valued extensions have a short form and a long form. The short form
34 is a list of names and values:
36  basicConstraints=critical,CA:true,pathlen:1
38 The long form allows the values to be placed in a separate section:
40  basicConstraints=critical,@bs_section
42  [bs_section]
44  CA=true
45  pathlen=1
47 Both forms are equivalent.
49 The syntax of raw extensions is governed by the extension code: it can
50 for example contain data in multiple sections. The correct syntax to
51 use is defined by the extension code itself: check out the certificate
52 policies extension for an example.
54 If an extension type is unsupported then the I<arbitrary> extension syntax
55 must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details.
57 =head1 STANDARD EXTENSIONS
59 The following sections describe each supported extension in detail.
61 =head2 Basic Constraints.
63 This is a multi valued extension which indicates whether a certificate is
64 a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
65 B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
66 non-negative value can be included.
68 For example:
70  basicConstraints=CA:TRUE
72  basicConstraints=CA:FALSE
74  basicConstraints=critical,CA:TRUE, pathlen:0
76 A CA certificate B<must> include the basicConstraints value with the CA field
77 set to TRUE. An end user certificate must either set CA to FALSE or exclude the
78 extension entirely. Some software may require the inclusion of basicConstraints
79 with CA set to FALSE for end entity certificates.
81 The pathlen parameter indicates the maximum number of CAs that can appear
82 below this one in a chain. So if you have a CA with a pathlen of zero it can
83 only be used to sign end user certificates and not further CAs.
86 =head2 Key Usage.
88 Key usage is a multi valued extension consisting of a list of names of the
89 permitted key usages.
91 The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
92 dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
93 and decipherOnly.
95 Examples:
97  keyUsage=digitalSignature, nonRepudiation
99  keyUsage=critical, keyCertSign
102 =head2 Extended Key Usage.
104 This extensions consists of a list of usages indicating purposes for which
105 the certificate public key can be used for,
107 These can either be object short names of the dotted numerical form of OIDs.
108 While any OID can be used only certain values make sense. In particular the
109 following PKIX, NS and MS values are meaningful:
111  Value                  Meaning
112  -----                  -------
113  serverAuth             SSL/TLS Web Server Authentication.
114  clientAuth             SSL/TLS Web Client Authentication.
115  codeSigning            Code signing.
116  emailProtection        E-mail Protection (S/MIME).
117  timeStamping           Trusted Timestamping
118  msCodeInd              Microsoft Individual Code Signing (authenticode)
119  msCodeCom              Microsoft Commercial Code Signing (authenticode)
120  msCTLSign              Microsoft Trust List Signing
121  msSGC                  Microsoft Server Gated Crypto
122  msEFS                  Microsoft Encrypted File System
123  nsSGC                  Netscape Server Gated Crypto
125 Examples:
127  extendedKeyUsage=critical,codeSigning,1.2.3.4
128  extendedKeyUsage=nsSGC,msSGC
131 =head2 Subject Key Identifier.
133 This is really a string extension and can take two possible values. Either
134 the word B<hash> which will automatically follow the guidelines in RFC3280
135 or a hex string giving the extension value to include. The use of the hex
136 string is strongly discouraged.
138 Example:
140  subjectKeyIdentifier=hash
143 =head2 Authority Key Identifier.
145 The authority key identifier extension permits two options. keyid and issuer:
146 both can take the optional value "always".
148 If the keyid option is present an attempt is made to copy the subject key
149 identifier from the parent certificate. If the value "always" is present
150 then an error is returned if the option fails.
152 The issuer option copies the issuer and serial number from the issuer
153 certificate. This will only be done if the keyid option fails or
154 is not included unless the "always" flag will always include the value.
156 Example:
158  authorityKeyIdentifier=keyid,issuer
161 =head2 Subject Alternative Name.
163 The subject alternative name extension allows various literal values to be
164 included in the configuration file. These include B<email> (an email address)
165 B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
166 registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
167 (a distinguished name) and otherName.
169 The email option include a special 'copy' value. This will automatically
170 include and email addresses contained in the certificate subject name in
171 the extension.
173 The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
175 The value of B<dirName> should point to a section containing the distinguished
176 name to use as a set of name value pairs. Multi values AVAs can be formed by
177 prefacing the name with a B<+> character.
179 otherName can include arbitrary data associated with an OID: the value
180 should be the OID followed by a semicolon and the content in standard
181 L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format.
183 Examples:
185  subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
186  subjectAltName=IP:192.168.7.1
187  subjectAltName=IP:13::17
188  subjectAltName=email:my@other.address,RID:1.2.3.4
189  subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
191  subjectAltName=dirName:dir_sect
193  [dir_sect]
194  C=UK
195  O=My Organization
196  OU=My Unit
197  CN=My Name
200 =head2 Issuer Alternative Name.
202 The issuer alternative name option supports all the literal options of
203 subject alternative name. It does B<not> support the email:copy option because
204 that would not make sense. It does support an additional issuer:copy option
205 that will copy all the subject alternative name values from the issuer 
206 certificate (if possible).
208 Example:
210  issuserAltName = issuer:copy
213 =head2 Authority Info Access.
215 The authority information access extension gives details about how to access
216 certain information relating to the CA. Its syntax is accessOID;location
217 where I<location> has the same syntax as subject alternative name (except
218 that email:copy is not supported). accessOID can be any valid OID but only
219 certain values are meaningful, for example OCSP and caIssuers.
221 Example:
223  authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
224  authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
227 =head2 CRL distribution points.
229 This is a multi-valued extension whose options can be either in name:value pair
230 using the same form as subject alternative name or a single value representing
231 a section name containing all the distribution point fields.
233 For a name:value pair a new DistributionPoint with the fullName field set to
234 the given value both the cRLissuer and reasons fields are omitted in this case.
236 In the single option case the section indicated contains values for each
237 field. In this section:
239 If the name is "fullname" the value field should contain the full name
240 of the distribution point in the same format as subject alternative name.
242 If the name is "relativename" then the value field should contain a section
243 name whose contents represent a DN fragment to be placed in this field.
245 The name "CRLIssuer" if present should contain a value for this field in
246 subject alternative name format.
248 If the name is "reasons" the value field should consist of a comma
249 separated field containing the reasons. Valid reasons are: "keyCompromise",
250 "CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
251 "certificateHold", "privilegeWithdrawn" and "AACompromise".
254 Simple examples:
256  crlDistributionPoints=URI:http://myhost.com/myca.crl
257  crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
259 Full distribution point example:
261  crlDistributionPoints=crldp1_section
263  [crldp1_section]
265  fullname=URI:http://myhost.com/myca.crl
266  CRLissuer=dirName:issuer_sect
267  reasons=keyCompromise, CACompromise
269  [issuer_sect]
270  C=UK
271  O=Organisation
272  CN=Some Name
274 =head2 Issuing Distribution Point
276 This extension should only appear in CRLs. It is a multi valued extension
277 whose syntax is similar to the "section" pointed to by the CRL distribution
278 points extension with a few differences.
280 The names "reasons" and "CRLissuer" are not recognized.
282 The name "onlysomereasons" is accepted which sets this field. The value is
283 in the same format as the CRL distribution point "reasons" field.
285 The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
286 the values should be a boolean value (TRUE or FALSE) to indicate the value of
287 the corresponding field.
289 Example:
291  issuingDistributionPoint=critical, @idp_section
293  [idp_section]
295  fullname=URI:http://myhost.com/myca.crl
296  indirectCRL=TRUE
297  onlysomereasons=keyCompromise, CACompromise
299  [issuer_sect]
300  C=UK
301  O=Organisation
302  CN=Some Name
305 =head2 Certificate Policies.
307 This is a I<raw> extension. All the fields of this extension can be set by
308 using the appropriate syntax.
310 If you follow the PKIX recommendations and just using one OID then you just
311 include the value of that OID. Multiple OIDs can be set separated by commas,
312 for example:
314  certificatePolicies= 1.2.4.5, 1.1.3.4
316 If you wish to include qualifiers then the policy OID and qualifiers need to
317 be specified in a separate section: this is done by using the @section syntax
318 instead of a literal OID value.
320 The section referred to must include the policy OID using the name
321 policyIdentifier, cPSuri qualifiers can be included using the syntax:
323  CPS.nnn=value
325 userNotice qualifiers can be set using the syntax:
327  userNotice.nnn=@notice
329 The value of the userNotice qualifier is specified in the relevant section.
330 This section can include explicitText, organization and noticeNumbers
331 options. explicitText and organization are text strings, noticeNumbers is a
332 comma separated list of numbers. The organization and noticeNumbers options
333 (if included) must BOTH be present. If you use the userNotice option with IE5
334 then you need the 'ia5org' option at the top level to modify the encoding:
335 otherwise it will not be interpreted properly.
337 Example:
339  certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
341  [polsect]
343  policyIdentifier = 1.3.5.8
344  CPS.1="http://my.host.name/"
345  CPS.2="http://my.your.name/"
346  userNotice.1=@notice
348  [notice]
350  explicitText="Explicit Text Here"
351  organization="Organisation Name"
352  noticeNumbers=1,2,3,4
354 The B<ia5org> option changes the type of the I<organization> field. In RFC2459
355 it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible.
356 Some software (for example some versions of MSIE) may require ia5org.
358 =head2 Policy Constraints
360 This is a multi-valued extension which consisting of the names
361 B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger
362 value. At least one component must be present.
364 Example:
366  policyConstraints = requireExplicitPolicy:3
369 =head2 Inhibit Any Policy
371 This is a string extension whose value must be a non negative integer.
373 Example:
375  inhibitAnyPolicy = 2
378 =head2 Name Constraints
380 The name constraints extension is a multi-valued extension. The name should
381 begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
382 the name and the value follows the syntax of subjectAltName except email:copy
383 is not supported and the B<IP> form should consist of an IP addresses and 
384 subnet mask separated by a B</>.
386 Examples:
388  nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
390  nameConstraints=permitted;email:.somedomain.com
392  nameConstraints=excluded;email:.com
395 =head2 OCSP No Check
397 The OCSP No Check extension is a string extension but its value is ignored.
399 Example:
401  noCheck = ignored
404 =head1 DEPRECATED EXTENSIONS
406 The following extensions are non standard, Netscape specific and largely
407 obsolete. Their use in new applications is discouraged.
409 =head2 Netscape String extensions.
411 Netscape Comment (B<nsComment>) is a string extension containing a comment
412 which will be displayed when the certificate is viewed in some browsers.
414 Example:
416  nsComment = "Some Random Comment"
418 Other supported extensions in this category are: B<nsBaseUrl>,
419 B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
420 and B<nsSslServerName>.
423 =head2 Netscape Certificate Type
425 This is a multi-valued extensions which consists of a list of flags to be
426 included. It was used to indicate the purposes for which a certificate could
427 be used. The basicConstraints, keyUsage and extended key usage extensions are
428 now used instead.
430 Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
431 B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
434 =head1 ARBITRARY EXTENSIONS
436 If an extension is not supported by the OpenSSL code then it must be encoded
437 using the arbitrary extension format. It is also possible to use the arbitrary
438 format for supported extensions. Extreme care should be taken to ensure that
439 the data is formatted correctly for the given extension type.
441 There are two ways to encode arbitrary extensions.
443 The first way is to use the word ASN1 followed by the extension content
444 using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>.
445 For example:
447  1.2.3.4=critical,ASN1:UTF8String:Some random data
449  1.2.3.4=ASN1:SEQUENCE:seq_sect
451  [seq_sect]
453  field1 = UTF8:field1
454  field2 = UTF8:field2
456 It is also possible to use the word DER to include the raw encoded data in any
457 extension.
459  1.2.3.4=critical,DER:01:02:03:04
460  1.2.3.4=DER:01020304
462 The value following DER is a hex dump of the DER encoding of the extension
463 Any extension can be placed in this form to override the default behaviour.
464 For example:
466  basicConstraints=critical,DER:00:01:02:03
468 =head1 WARNING
470 There is no guarantee that a specific implementation will process a given
471 extension. It may therefore be sometimes possible to use certificates for
472 purposes prohibited by their extensions because a specific application does
473 not recognize or honour the values of the relevant extensions.
475 The DER and ASN1 options should be used with caution. It is possible to create
476 totally invalid extensions if they are not used carefully.
479 =head1 NOTES
481 If an extension is multi-value and a field value must contain a comma the long
482 form must be used otherwise the comma would be misinterpreted as a field
483 separator. For example:
485  subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
487 will produce an error but the equivalent form:
489  subjectAltName=@subject_alt_section
491  [subject_alt_section]
492  subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
494 is valid. 
496 Due to the behaviour of the OpenSSL B<conf> library the same field name
497 can only occur once in a section. This means that:
499  subjectAltName=@alt_section
501  [alt_section]
503  email=steve@here
504  email=steve@there
506 will only recognize the last value. This can be worked around by using the form:
508  [alt_section]
510  email.1=steve@here
511  email.2=steve@there
513 =head1 HISTORY
515 The X509v3 extension code was first added to OpenSSL 0.9.2.
517 Policy mappings, inhibit any policy and name constraints support was added in
518 OpenSSL 0.9.8
520 The B<directoryName> and B<otherName> option as well as the B<ASN1> option
521 for arbitrary extensions was added in OpenSSL 0.9.8
523 =head1 SEE ALSO
525 L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>,
526 L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
529 =cut