]>
Commit | Line | Data |
---|---|---|
19f39703 DSH |
1 | =pod |
2 | ||
401ee37a DSH |
3 | =for comment openssl_manual_section:5 |
4 | ||
19f39703 DSH |
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 | |
2932ad56 | 55 | must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. |
19f39703 DSH |
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 | ||
4c583c36 | 91 | The supported names are: digitalSignature, nonRepudiation, keyEncipherment, |
19f39703 DSH |
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 | ||
981b5bb8 | 107 | These can either be object short names or the dotted numerical form of OIDs. |
19f39703 DSH |
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 | ||
1bc74519 RS |
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 | OCSPSigning OCSP Signing | |
119 | ipsecIKE ipsec Internet Key Exchnage | |
120 | msCodeInd Microsoft Individual Code Signing (authenticode) | |
121 | msCodeCom Microsoft Commercial Code Signing (authenticode) | |
122 | msCTLSign Microsoft Trust List Signing | |
123 | msEFS Microsoft Encrypted File System | |
19f39703 DSH |
124 | |
125 | Examples: | |
126 | ||
127 | extendedKeyUsage=critical,codeSigning,1.2.3.4 | |
0bc2f365 | 128 | extendedKeyUsage=serverAuth,clientAuth |
19f39703 DSH |
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 | |
5dd87981 DSH |
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 | |
19f39703 DSH |
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 | ||
37dccd8f DSH |
173 | The IP address used in the B<IP> options can be in either IPv4 or IPv6 format. |
174 | ||
19f39703 DSH |
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 | |
fc1d88f0 | 177 | prefacing the name with a B<+> character. |
19f39703 DSH |
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 | |
9b86974e | 181 | L<ASN1_generate_nconf(3)> format. |
19f39703 DSH |
182 | |
183 | Examples: | |
184 | ||
185 | subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ | |
37dccd8f DSH |
186 | subjectAltName=IP:192.168.7.1 |
187 | subjectAltName=IP:13::17 | |
19f39703 DSH |
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 | |
4c583c36 | 205 | that will copy all the subject alternative name values from the issuer |
19f39703 DSH |
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 | ||
83357f04 DSH |
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. | |
19f39703 | 232 | |
83357f04 DSH |
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. | |
19f39703 | 235 | |
83357f04 DSH |
236 | In the single option case the section indicated contains values for each |
237 | field. In this section: | |
19f39703 | 238 | |
83357f04 DSH |
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: | |
19f39703 DSH |
255 | |
256 | crlDistributionPoints=URI:http://myhost.com/myca.crl | |
257 | crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl | |
258 | ||
83357f04 DSH |
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 | ||
085ccc54 | 304 | |
19f39703 DSH |
305 | =head2 Certificate Policies. |
306 | ||
5dd87981 | 307 | This is a I<raw> extension. All the fields of this extension can be set by |
19f39703 DSH |
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 | ||
37dccd8f DSH |
358 | =head2 Policy Constraints |
359 | ||
360 | This is a multi-valued extension which consisting of the names | |
4c583c36 | 361 | B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer |
37dccd8f DSH |
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 | ||
19f39703 | 377 | |
5dd87981 DSH |
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 | |
4c583c36 | 383 | is not supported and the B<IP> form should consist of an IP addresses and |
5dd87981 DSH |
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 | |
085ccc54 | 393 | |
83357f04 | 394 | |
137de5b1 DSH |
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 | ||
5dd87981 | 403 | |
ba67253d RS |
404 | =head2 TLS Feature (aka Must Staple) |
405 | ||
406 | This is a multi-valued extension consisting of a list of TLS extension | |
407 | identifiers. Each identifier may be a number (0..65535) or a supported name. | |
408 | When a TLS client sends a listed extension, the TLS server is expected to | |
409 | include that extension in its reply. | |
410 | ||
411 | The supported names are: B<status_request> and B<status_request_v2>. | |
412 | ||
413 | Example: | |
414 | ||
415 | tlsfeature = status_request | |
416 | ||
417 | ||
19f39703 DSH |
418 | =head1 DEPRECATED EXTENSIONS |
419 | ||
5dd87981 DSH |
420 | The following extensions are non standard, Netscape specific and largely |
421 | obsolete. Their use in new applications is discouraged. | |
19f39703 DSH |
422 | |
423 | =head2 Netscape String extensions. | |
424 | ||
425 | Netscape Comment (B<nsComment>) is a string extension containing a comment | |
426 | which will be displayed when the certificate is viewed in some browsers. | |
427 | ||
428 | Example: | |
429 | ||
430 | nsComment = "Some Random Comment" | |
431 | ||
432 | Other supported extensions in this category are: B<nsBaseUrl>, | |
433 | B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> | |
434 | and B<nsSslServerName>. | |
435 | ||
436 | ||
437 | =head2 Netscape Certificate Type | |
438 | ||
439 | This is a multi-valued extensions which consists of a list of flags to be | |
440 | included. It was used to indicate the purposes for which a certificate could | |
441 | be used. The basicConstraints, keyUsage and extended key usage extensions are | |
442 | now used instead. | |
443 | ||
444 | Acceptable values for nsCertType are: B<client>, B<server>, B<email>, | |
445 | B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. | |
446 | ||
447 | ||
448 | =head1 ARBITRARY EXTENSIONS | |
449 | ||
450 | If an extension is not supported by the OpenSSL code then it must be encoded | |
451 | using the arbitrary extension format. It is also possible to use the arbitrary | |
452 | format for supported extensions. Extreme care should be taken to ensure that | |
453 | the data is formatted correctly for the given extension type. | |
454 | ||
455 | There are two ways to encode arbitrary extensions. | |
456 | ||
457 | The first way is to use the word ASN1 followed by the extension content | |
9b86974e | 458 | using the same syntax as L<ASN1_generate_nconf(3)>. |
51cc37b6 | 459 | For example: |
19f39703 DSH |
460 | |
461 | 1.2.3.4=critical,ASN1:UTF8String:Some random data | |
462 | ||
463 | 1.2.3.4=ASN1:SEQUENCE:seq_sect | |
464 | ||
465 | [seq_sect] | |
466 | ||
467 | field1 = UTF8:field1 | |
468 | field2 = UTF8:field2 | |
469 | ||
470 | It is also possible to use the word DER to include the raw encoded data in any | |
471 | extension. | |
472 | ||
473 | 1.2.3.4=critical,DER:01:02:03:04 | |
474 | 1.2.3.4=DER:01020304 | |
475 | ||
476 | The value following DER is a hex dump of the DER encoding of the extension | |
477 | Any extension can be placed in this form to override the default behaviour. | |
478 | For example: | |
479 | ||
480 | basicConstraints=critical,DER:00:01:02:03 | |
481 | ||
482 | =head1 WARNING | |
483 | ||
484 | There is no guarantee that a specific implementation will process a given | |
485 | extension. It may therefore be sometimes possible to use certificates for | |
486 | purposes prohibited by their extensions because a specific application does | |
487 | not recognize or honour the values of the relevant extensions. | |
488 | ||
489 | The DER and ASN1 options should be used with caution. It is possible to create | |
490 | totally invalid extensions if they are not used carefully. | |
491 | ||
492 | ||
493 | =head1 NOTES | |
494 | ||
495 | If an extension is multi-value and a field value must contain a comma the long | |
496 | form must be used otherwise the comma would be misinterpreted as a field | |
497 | separator. For example: | |
498 | ||
499 | subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar | |
500 | ||
501 | will produce an error but the equivalent form: | |
502 | ||
503 | subjectAltName=@subject_alt_section | |
504 | ||
505 | [subject_alt_section] | |
506 | subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar | |
507 | ||
4c583c36 | 508 | is valid. |
19f39703 DSH |
509 | |
510 | Due to the behaviour of the OpenSSL B<conf> library the same field name | |
511 | can only occur once in a section. This means that: | |
512 | ||
513 | subjectAltName=@alt_section | |
514 | ||
515 | [alt_section] | |
516 | ||
517 | email=steve@here | |
518 | email=steve@there | |
519 | ||
520 | will only recognize the last value. This can be worked around by using the form: | |
521 | ||
522 | [alt_section] | |
523 | ||
524 | email.1=steve@here | |
525 | email.2=steve@there | |
5dd87981 | 526 | |
5dd87981 DSH |
527 | =head1 SEE ALSO |
528 | ||
9b86974e RS |
529 | L<req(1)>, L<ca(1)>, L<x509(1)>, |
530 | L<ASN1_generate_nconf(3)> | |
5dd87981 DSH |
531 | |
532 | ||
e2f92610 RS |
533 | =cut |
534 | ||
535 | =head1 COPYRIGHT | |
536 | ||
537 | Copyright 2004-2016 The OpenSSL Project Authors. All Rights Reserved. | |
538 | ||
539 | Licensed under the OpenSSL license (the "License"). You may not use | |
540 | this file except in compliance with the License. You can obtain a copy | |
541 | in the file LICENSE in the source distribution or at | |
542 | L<https://www.openssl.org/source/license.html>. | |
543 | ||
5dd87981 | 544 | =cut |