Import OpenSSL-1.0.1h.
[dragonfly.git] / crypto / openssl / doc / apps / x509v3_config.pod
CommitLineData
730b1645
PA
1=pod
2
3=for comment openssl_manual_section:5
4
5=head1 NAME
6
7x509v3_config - X509 V3 certificate extension configuration format
8
9=head1 DESCRIPTION
10
11Several of the OpenSSL utilities can add extensions to a certificate or
12certificate request based on the contents of a configuration file.
13
14Typically the application will contain an option to point to an extension
15section. Each line of the extension section takes the form:
16
17 extension_name=[critical,] extension_options
18
19If B<critical> is present then the extension will be critical.
20
21The format of B<extension_options> depends on the value of B<extension_name>.
22
23There are four main types of extension: I<string> extensions, I<multi-valued>
24extensions, I<raw> and I<arbitrary> extensions.
25
26String extensions simply have a string which contains either the value itself
27or how it is obtained.
28
29For example:
30
31 nsComment="This is a Comment"
32
33Multi-valued extensions have a short form and a long form. The short form
34is a list of names and values:
35
36 basicConstraints=critical,CA:true,pathlen:1
37
38The 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
47Both forms are equivalent.
48
49The syntax of raw extensions is governed by the extension code: it can
50for example contain data in multiple sections. The correct syntax to
51use is defined by the extension code itself: check out the certificate
52policies extension for an example.
53
54If an extension type is unsupported then the I<arbitrary> extension syntax
919b01cc 55must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details.
730b1645
PA
56
57=head1 STANDARD EXTENSIONS
58
59The following sections describe each supported extension in detail.
60
61=head2 Basic Constraints.
62
63This is a multi valued extension which indicates whether a certificate is
64a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or
65B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an
66non-negative value can be included.
67
68For example:
69
70 basicConstraints=CA:TRUE
71
72 basicConstraints=CA:FALSE
73
74 basicConstraints=critical,CA:TRUE, pathlen:0
75
76A CA certificate B<must> include the basicConstraints value with the CA field
77set to TRUE. An end user certificate must either set CA to FALSE or exclude the
78extension entirely. Some software may require the inclusion of basicConstraints
79with CA set to FALSE for end entity certificates.
80
81The pathlen parameter indicates the maximum number of CAs that can appear
82below this one in a chain. So if you have a CA with a pathlen of zero it can
83only be used to sign end user certificates and not further CAs.
84
85
86=head2 Key Usage.
87
88Key usage is a multi valued extension consisting of a list of names of the
89permitted key usages.
90
91The supporte names are: digitalSignature, nonRepudiation, keyEncipherment,
92dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly
93and decipherOnly.
94
95Examples:
96
97 keyUsage=digitalSignature, nonRepudiation
98
99 keyUsage=critical, keyCertSign
100
101
102=head2 Extended Key Usage.
103
104This extensions consists of a list of usages indicating purposes for which
105the certificate public key can be used for,
106
107These can either be object short names of the dotted numerical form of OIDs.
108While any OID can be used only certain values make sense. In particular the
109following 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
125Examples:
126
127 extendedKeyUsage=critical,codeSigning,1.2.3.4
128 extendedKeyUsage=nsSGC,msSGC
129
130
131=head2 Subject Key Identifier.
132
133This is really a string extension and can take two possible values. Either
134the word B<hash> which will automatically follow the guidelines in RFC3280
135or a hex string giving the extension value to include. The use of the hex
136string is strongly discouraged.
137
138Example:
139
140 subjectKeyIdentifier=hash
141
142
143=head2 Authority Key Identifier.
144
145The authority key identifier extension permits two options. keyid and issuer:
146both can take the optional value "always".
147
148If the keyid option is present an attempt is made to copy the subject key
149identifier from the parent certificate. If the value "always" is present
150then an error is returned if the option fails.
151
152The issuer option copies the issuer and serial number from the issuer
153certificate. This will only be done if the keyid option fails or
154is not included unless the "always" flag will always include the value.
155
156Example:
157
158 authorityKeyIdentifier=keyid,issuer
159
160
161=head2 Subject Alternative Name.
162
163The subject alternative name extension allows various literal values to be
164included in the configuration file. These include B<email> (an email address)
165B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a
166registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName>
167(a distinguished name) and otherName.
168
169The email option include a special 'copy' value. This will automatically
170include and email addresses contained in the certificate subject name in
171the extension.
172
173The IP address used in the B<IP> options can be in either IPv4 or IPv6 format.
174
175The value of B<dirName> should point to a section containing the distinguished
176name to use as a set of name value pairs. Multi values AVAs can be formed by
177preceeding the name with a B<+> character.
178
179otherName can include arbitrary data associated with an OID: the value
180should be the OID followed by a semicolon and the content in standard
919b01cc 181L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format.
730b1645
PA
182
183Examples:
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
202The issuer alternative name option supports all the literal options of
203subject alternative name. It does B<not> support the email:copy option because
204that would not make sense. It does support an additional issuer:copy option
205that will copy all the subject alternative name values from the issuer
206certificate (if possible).
207
208Example:
209
210 issuserAltName = issuer:copy
211
212
213=head2 Authority Info Access.
214
215The authority information access extension gives details about how to access
216certain information relating to the CA. Its syntax is accessOID;location
217where I<location> has the same syntax as subject alternative name (except
218that email:copy is not supported). accessOID can be any valid OID but only
219certain values are meaningful, for example OCSP and caIssuers.
220
221Example:
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
919b01cc
PA
229This is a multi-valued extension whose options can be either in name:value pair
230using the same form as subject alternative name or a single value representing
231a section name containing all the distribution point fields.
730b1645 232
919b01cc
PA
233For a name:value pair a new DistributionPoint with the fullName field set to
234the given value both the cRLissuer and reasons fields are omitted in this case.
730b1645 235
919b01cc
PA
236In the single option case the section indicated contains values for each
237field. In this section:
730b1645 238
919b01cc
PA
239If the name is "fullname" the value field should contain the full name
240of the distribution point in the same format as subject alternative name.
241
242If the name is "relativename" then the value field should contain a section
243name whose contents represent a DN fragment to be placed in this field.
244
245The name "CRLIssuer" if present should contain a value for this field in
246subject alternative name format.
247
248If the name is "reasons" the value field should consist of a comma
249separated field containing the reasons. Valid reasons are: "keyCompromise",
250"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation",
251"certificateHold", "privilegeWithdrawn" and "AACompromise".
252
253
254Simple examples:
730b1645
PA
255
256 crlDistributionPoints=URI:http://myhost.com/myca.crl
257 crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
258
919b01cc
PA
259Full 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
276This extension should only appear in CRLs. It is a multi valued extension
277whose syntax is similar to the "section" pointed to by the CRL distribution
278points extension with a few differences.
279
280The names "reasons" and "CRLissuer" are not recognized.
281
282The name "onlysomereasons" is accepted which sets this field. The value is
283in the same format as the CRL distribution point "reasons" field.
284
285The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted
286the values should be a boolean value (TRUE or FALSE) to indicate the value of
287the corresponding field.
288
289Example:
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
4bb195ec 304
730b1645
PA
305=head2 Certificate Policies.
306
307This is a I<raw> extension. All the fields of this extension can be set by
308using the appropriate syntax.
309
310If you follow the PKIX recommendations and just using one OID then you just
311include the value of that OID. Multiple OIDs can be set separated by commas,
312for example:
313
314 certificatePolicies= 1.2.4.5, 1.1.3.4
315
316If you wish to include qualifiers then the policy OID and qualifiers need to
317be specified in a separate section: this is done by using the @section syntax
318instead of a literal OID value.
319
320The section referred to must include the policy OID using the name
321policyIdentifier, cPSuri qualifiers can be included using the syntax:
322
323 CPS.nnn=value
324
325userNotice qualifiers can be set using the syntax:
326
327 userNotice.nnn=@notice
328
329The value of the userNotice qualifier is specified in the relevant section.
330This section can include explicitText, organization and noticeNumbers
331options. explicitText and organization are text strings, noticeNumbers is a
332comma separated list of numbers. The organization and noticeNumbers options
333(if included) must BOTH be present. If you use the userNotice option with IE5
334then you need the 'ia5org' option at the top level to modify the encoding:
335otherwise it will not be interpreted properly.
336
337Example:
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
354The B<ia5org> option changes the type of the I<organization> field. In RFC2459
355it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible.
356Some software (for example some versions of MSIE) may require ia5org.
357
358=head2 Policy Constraints
359
360This is a multi-valued extension which consisting of the names
361B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger
362value. At least one component must be present.
363
364Example:
365
366 policyConstraints = requireExplicitPolicy:3
367
368
369=head2 Inhibit Any Policy
370
371This is a string extension whose value must be a non negative integer.
372
373Example:
374
375 inhibitAnyPolicy = 2
376
377
378=head2 Name Constraints
379
380The name constraints extension is a multi-valued extension. The name should
381begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
382the name and the value follows the syntax of subjectAltName except email:copy
383is not supported and the B<IP> form should consist of an IP addresses and
384subnet mask separated by a B</>.
385
386Examples:
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
4bb195ec 393
919b01cc
PA
394
395=head2 OCSP No Check
396
397The OCSP No Check extension is a string extension but its value is ignored.
398
399Example:
400
401 noCheck = ignored
402
730b1645
PA
403
404=head1 DEPRECATED EXTENSIONS
405
406The following extensions are non standard, Netscape specific and largely
407obsolete. Their use in new applications is discouraged.
408
409=head2 Netscape String extensions.
410
411Netscape Comment (B<nsComment>) is a string extension containing a comment
412which will be displayed when the certificate is viewed in some browsers.
413
414Example:
415
416 nsComment = "Some Random Comment"
417
418Other supported extensions in this category are: B<nsBaseUrl>,
419B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
420and B<nsSslServerName>.
421
422
423=head2 Netscape Certificate Type
424
425This is a multi-valued extensions which consists of a list of flags to be
426included. It was used to indicate the purposes for which a certificate could
427be used. The basicConstraints, keyUsage and extended key usage extensions are
428now used instead.
429
430Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
431B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
432
433
434=head1 ARBITRARY EXTENSIONS
435
436If an extension is not supported by the OpenSSL code then it must be encoded
437using the arbitrary extension format. It is also possible to use the arbitrary
438format for supported extensions. Extreme care should be taken to ensure that
439the data is formatted correctly for the given extension type.
440
441There are two ways to encode arbitrary extensions.
442
443The first way is to use the word ASN1 followed by the extension content
919b01cc
PA
444using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>.
445For example:
730b1645
PA
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
456It is also possible to use the word DER to include the raw encoded data in any
457extension.
458
459 1.2.3.4=critical,DER:01:02:03:04
460 1.2.3.4=DER:01020304
461
462The value following DER is a hex dump of the DER encoding of the extension
463Any extension can be placed in this form to override the default behaviour.
464For example:
465
466 basicConstraints=critical,DER:00:01:02:03
467
468=head1 WARNING
469
470There is no guarantee that a specific implementation will process a given
471extension. It may therefore be sometimes possible to use certificates for
472purposes prohibited by their extensions because a specific application does
473not recognize or honour the values of the relevant extensions.
474
475The DER and ASN1 options should be used with caution. It is possible to create
476totally invalid extensions if they are not used carefully.
477
478
479=head1 NOTES
480
481If an extension is multi-value and a field value must contain a comma the long
482form must be used otherwise the comma would be misinterpreted as a field
483separator. For example:
484
485 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
486
487will 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
494is valid.
495
496Due to the behaviour of the OpenSSL B<conf> library the same field name
497can 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
506will 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
515The X509v3 extension code was first added to OpenSSL 0.9.2.
516
517Policy mappings, inhibit any policy and name constraints support was added in
518OpenSSL 0.9.8
519
520The B<directoryName> and B<otherName> option as well as the B<ASN1> option
521for arbitrary extensions was added in OpenSSL 0.9.8
522
523=head1 SEE ALSO
524
919b01cc
PA
525L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>,
526L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>
730b1645
PA
527
528
529=cut