correct docs
[openssl.git] / doc / apps / x509v3_config.pod
1 =pod
2
3 =for comment openssl_manual_section:5
4
5 =head1 NAME
6
7 x509v3_config - X509 V3 certificate extension configuration format
8
9 =head1 DESCRIPTION
10
11 Several of the OpenSSL utilities can add extensions to a certificate or
12 certificate request based on the contents of a configuration file.
13
14 Typically the application will contain an option to point to an extension
15 section. Each line of the extension section takes the form:
16
17  extension_name=[critical,] extension_options
18
19 If B<critical> is present then the extension will be critical.
20
21 The format of B<extension_options> depends on the value of B<extension_name>.
22
23 There are four main types of extension: I<string> extensions, I<multi-valued>
24 extensions, I<raw> and I<arbitrary> extensions.
25
26 String extensions simply have a string which contains either the value itself
27 or how it is obtained.
28
29 For example:
30
31  nsComment="This is a Comment"
32
33 Multi-valued extensions have a short form and a long form. The short form
34 is a list of names and values:
35
36  basicConstraints=critical,CA:true,pathlen:1
37
38 The long form allows the values to be placed in a separate section:
39
40  basicConstraints=critical,@bs_section
41
42  [bs_section]
43
44  CA=true
45  pathlen=1
46
47 Both forms are equivalent.
48
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.
53
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.
56
57 =head1 STANDARD EXTENSIONS
58
59 The following sections describe each supported extension in detail.
60
61 =head2 Basic Constraints.
62
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.
67
68 For example:
69
70  basicConstraints=CA:TRUE
71
72  basicConstraints=CA:FALSE
73
74  basicConstraints=critical,CA:TRUE, pathlen:0
75
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.
80
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.
84
85
86 =head2 Key Usage.
87
88 Key usage is a multi valued extension consisting of a list of names of the
89 permitted key usages.
90
91 The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
92 dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
93 and decipherOnly.
94
95 Examples:
96
97  keyUsage=digitalSignature, nonRepudiation
98
99  keyUsage=critical, keyCertSign
100
101
102 =head2 Extended Key Usage.
103
104 This extensions consists of a list of usages indicating purposes for which
105 the certificate public key can be used for,
106
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:
110
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
124
125 Examples:
126
127  extendedKeyUsage=critical,codeSigning,1.2.3.4
128  extendedKeyUsage=nsSGC,msSGC
129
130
131 =head2 Subject Key Identifier.
132
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.
137
138 Example:
139
140  subjectKeyIdentifier=hash
141
142
143 =head2 Authority Key Identifier.
144
145 The authority key identifier extension permits two options. keyid and issuer:
146 both can take the optional value "always".
147
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.
151
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.
155
156 Example:
157
158  authorityKeyIdentifier=keyid,issuer
159
160
161 =head2 Subject Alternative Name.
162
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.
168
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.
172
173 The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
174
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 preceeding the name with a B<+> character.
178
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.
182
183 Examples:
184
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
190
191  subjectAltName=dirName:dir_sect
192
193  [dir_sect]
194  C=UK
195  O=My Organization
196  OU=My Unit
197  CN=My Name
198
199
200 =head2 Issuer Alternative Name.
201
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).
207
208 Example:
209
210  issuserAltName = issuer:copy
211
212
213 =head2 Authority Info Access.
214
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.
220
221 Example:
222
223  authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
224  authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
225
226
227 =head2 CRL distribution points.
228
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.
232
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.
235
236 In the single option case the section indicated contains values for each
237 field. In this section:
238
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.
241
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.
244
245 The name "CRLIssuer" if present should contain a value for this field in
246 subject alternative name format.
247
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".
252
253
254 Simple examples:
255
256  crlDistributionPoints=URI:http://myhost.com/myca.crl
257  crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
258
259 Full distribution point example:
260
261  crlDistributionPoints=crldp1_section
262
263  [crldp1_section]
264
265  fullname=URI:http://myhost.com/myca.crl
266  CRLissuer=dirName:issuer_sect
267  reasons=keyCompromise, CACompromise
268
269  [issuer_sect]
270  C=UK
271  O=Organisation
272  CN=Some Name
273
274 =head2 Issuing Distribution Point
275
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.
279
280 The names "reasons" and "CRLissuer" are not recognized.
281
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.
284
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.
288
289 Example:
290
291  issuingDistributionPoint=critical, @idp_section
292
293  [idp_section]
294
295  fullname=URI:http://myhost.com/myca.crl
296  indirectCRL=TRUE
297  onlysomereasons=keyCompromise, CACompromise
298
299  [issuer_sect]
300  C=UK
301  O=Organisation
302  CN=Some Name
303
304  
305 =head2 Certificate Policies.
306
307 This is a I<raw> extension. All the fields of this extension can be set by
308 using the appropriate syntax.
309
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:
313
314  certificatePolicies= 1.2.4.5, 1.1.3.4
315
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.
319
320 The section referred to must include the policy OID using the name
321 policyIdentifier, cPSuri qualifiers can be included using the syntax:
322
323  CPS.nnn=value
324
325 userNotice qualifiers can be set using the syntax:
326
327  userNotice.nnn=@notice
328
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.
336
337 Example:
338
339  certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
340
341  [polsect]
342
343  policyIdentifier = 1.3.5.8
344  CPS.1="http://my.host.name/"
345  CPS.2="http://my.your.name/"
346  userNotice.1=@notice
347
348  [notice]
349
350  explicitText="Explicit Text Here"
351  organization="Organisation Name"
352  noticeNumbers=1,2,3,4
353
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.
357
358 =head2 Policy Constraints
359
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.
363
364 Example:
365
366  policyConstraints = requireExplicitPolicy:3
367
368
369 =head2 Inhibit Any Policy
370
371 This is a string extension whose value must be a non negative integer.
372
373 Example:
374
375  inhibitAnyPolicy = 2
376
377
378 =head2 Name Constraints
379
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</>.
385
386 Examples:
387
388  nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
389
390  nameConstraints=permitted;email:.somedomain.com
391
392  nameConstraints=excluded;email:.com
393 issuingDistributionPoint = idp_section
394
395 =head2 OCSP No Check
396
397 The OCSP No Check extension is a string extension but its value is ignored.
398
399 Example:
400
401  noCheck = ignored
402
403
404 =head1 DEPRECATED EXTENSIONS
405
406 The following extensions are non standard, Netscape specific and largely
407 obsolete. Their use in new applications is discouraged.
408
409 =head2 Netscape String extensions.
410
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.
413
414 Example:
415
416  nsComment = "Some Random Comment"
417
418 Other supported extensions in this category are: B<nsBaseUrl>,
419 B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
420 and B<nsSslServerName>.
421
422
423 =head2 Netscape Certificate Type
424
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.
429
430 Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
431 B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
432
433
434 =head1 ARBITRARY EXTENSIONS
435
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.
440
441 There are two ways to encode arbitrary extensions.
442
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:
446
447  1.2.3.4=critical,ASN1:UTF8String:Some random data
448
449  1.2.3.4=ASN1:SEQUENCE:seq_sect
450
451  [seq_sect]
452
453  field1 = UTF8:field1
454  field2 = UTF8:field2
455
456 It is also possible to use the word DER to include the raw encoded data in any
457 extension.
458
459  1.2.3.4=critical,DER:01:02:03:04
460  1.2.3.4=DER:01020304
461
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:
465
466  basicConstraints=critical,DER:00:01:02:03
467
468 =head1 WARNING
469
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.
474
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.
477
478
479 =head1 NOTES
480
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:
484
485  subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
486
487 will produce an error but the equivalent form:
488
489  subjectAltName=@subject_alt_section
490
491  [subject_alt_section]
492  subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
493
494 is valid. 
495
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:
498
499  subjectAltName=@alt_section
500
501  [alt_section]
502
503  email=steve@here
504  email=steve@there
505
506 will only recognize the last value. This can be worked around by using the form:
507
508  [alt_section]
509
510  email.1=steve@here
511  email.2=steve@there
512
513 =head1 HISTORY
514
515 The X509v3 extension code was first added to OpenSSL 0.9.2.
516
517 Policy mappings, inhibit any policy and name constraints support was added in
518 OpenSSL 0.9.8
519
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
522
523 =head1 SEE ALSO
524
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)>
527
528
529 =cut