Revise x509v3_config.pod
[openssl.git] / doc / man5 / x509v3_config.pod
1 =pod
2
3 =head1 NAME
4
5 x509v3_config - X509 V3 certificate extension configuration format
6
7 =head1 DESCRIPTION
8
9 Several OpenSSL commands can add extensions to a certificate or
10 certificate request based on the contents of a configuration file.
11 The syntax of this file is described in L<config(5)>.
12 The commands typically have an option to specify the name of the configuration
13 file, and a section within that file; see the documentation of the
14 individual command for details.
15
16 This page uses B<extensions> as the name of the section, when needed
17 in examples.
18
19 Each entry in the extension section takes the form:
20
21  name = [critical, ]value(s)
22
23 If B<critical> is present then the extension will be marked as critical.
24
25 The format of B<values> depends on the value of B<name>, many have a
26 type-value pairing where the type and value are separated by a colon.
27 There are four main types of extension:
28
29  string
30  multi-valued
31  raw
32  arbitrary
33
34 Each is described in the following paragraphs.
35
36 String extensions simply have a string which contains either the value itself
37 or how it is obtained.
38
39 Multi-valued extensions have a short form and a long form. The short form
40 is a commma-separated list of names and values:
41
42  basicConstraints = critical, CA:true, pathlen:1
43
44 The long form allows the values to be placed in a separate section:
45
46  [extensions]
47  basicConstraints = critical, @basic_constraints
48
49  [basic_constraints]
50  CA = true
51  pathlen = 1
52
53 Both forms are equivalent.
54
55 If an extension is multi-value and a field value must contain a comma the long
56 form must be used otherwise the comma would be misinterpreted as a field
57 separator. For example:
58
59  subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
60
61 will produce an error but the equivalent form:
62
63  [extensions]
64  subjectAltName = @subject_alt_section
65
66  [subject_alt_section]
67  subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
68
69 is valid.
70
71 OpenSSL does not support multiple occurences of the same field within a
72 section. In this example:
73
74  [extensions]
75  subjectAltName = @alt_section
76
77  [alt_section]
78  email = steve@here
79  email = steve@there
80
81 will only recognize the last value.  To specify multiple values append a
82 numeric identifier, as shown here:
83
84  [extensions]
85  subjectAltName = @alt_section
86
87  [alt_section]
88  email.1 = steve@here
89  email.2 = steve@there
90
91 The syntax of raw extensions is defined by the source code that parses
92 the extension but should be documened.
93 See L</Certificate Policies> for an example of a raw extension.
94
95 If an extension type is unsupported, then the I<arbitrary> extension syntax
96 must be used, see the L</ARBITRARY EXTENSIONS> section for more details.
97
98 =head1 STANDARD EXTENSIONS
99
100 The following sections describe the syntax of each supported extension.
101 They do not define the semantics of the extension.
102
103 =head2 Basic Constraints
104
105 This is a multi-valued extension which indicates whether a certificate is
106 a CA certificate. The first value is B<CA> followed by B<TRUE> or
107 B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a
108 non-negative value can be included.
109
110 For example:
111
112  basicConstraints = CA:TRUE
113
114  basicConstraints = CA:FALSE
115
116  basicConstraints = critical, CA:TRUE, pathlen:1
117
118 A CA certificate I<must> include the B<basicConstraints> name with the B<CA>
119 parameter set to B<TRUE>. An end-user certificate must either have B<CA:FALSE>
120 or omit the extension entirely.
121 The B<pathlen> parameter specifies the maximum number of CAs that can appear
122 below this one in a chain. A B<pathlen> of zero means the CA cannot sign
123 any sub-CA's, and can only sign end-entity certificates.
124
125 =head2 Key Usage
126
127 Key usage is a multi-valued extension consisting of a list of names of
128 the permitted key usages.  The defined values are: C<digitalSignature>,
129 C<nonRepudiation>, C<keyEncipherment>, C<dataEncipherment>, C<keyAgreement>,
130 C<keyCertSign>, C<cRLSign>, C<encipherOnly>, and C<decipherOnly>.
131
132 Examples:
133
134  keyUsage = digitalSignature, nonRepudiation
135
136  keyUsage = critical, keyCertSign
137
138 =head2 Extended Key Usage
139
140 This extension consists of a list of values indicating purposes for which
141 the certificate public key can be used for, Each value can be either a
142 short text name or an OID.
143 The following text names, and their intended meaning, are known:
144
145  Value                  Meaning
146  -----                  -------
147  serverAuth             SSL/TLS Web Server Authentication
148  clientAuth             SSL/TLS Web Client Authentication
149  codeSigning            Code signing
150  emailProtection        E-mail Protection (S/MIME)
151  timeStamping           Trusted Timestamping
152  OCSPSigning            OCSP Signing
153  ipsecIKE               ipsec Internet Key Exchange
154  msCodeInd              Microsoft Individual Code Signing (authenticode)
155  msCodeCom              Microsoft Commercial Code Signing (authenticode)
156  msCTLSign              Microsoft Trust List Signing
157  msEFS                  Microsoft Encrypted File System
158
159 Examples:
160
161  extendedKeyUsage = critical, codeSigning, 1.2.3.4
162
163  extendedKeyUsage = serverAuth, clientAuth
164
165 =head2 Subject Key Identifier
166
167 This is a string extension with one of two legal values. If it is the word
168 B<hash>, then OpenSSL will follow the process in RFC 5280 to calculate the
169 hash value.
170 Otherwise, the value should be a hex string to output directly, however this
171 is strongly discouraged.
172
173 Example:
174
175  subjectKeyIdentifier = hash
176
177 =head2 Authority Key Identifier
178
179 This extension has two options, B<keyid> and B<issuer>. Either or both
180 can have the value B<always>, indicated by putting a colon between
181 the option and its value.
182
183 If B<keyid> is present, than an attempt is made to copy the subject key
184 identifier from the parent certificate. If the value B<always> is present,
185 then an error can be returned if the option fails.  If B<issuer> is present,
186 an attempt is made to copy the issuer and serial number from the parent
187 certificate. This is done if the B<keyid> option fails, or if B<issuer>
188 has B<always> specified.
189
190 Examples:
191
192  authorityKeyIdentifier = keyid, issuer
193
194  authorityKeyIdentifier = keyid, issuer:always
195
196 =head2 Subject Alternative Name
197
198 This is a multi-valued extension that supports several types of name
199 identifier, including
200 B<email> (an email address),
201 B<URI> (a uniform resource indicator),
202 B<DNS> (a DNS domain name),
203 B<RID> (a registered ID: OBJECT IDENTIFIER),
204 B<IP> (an IP address),
205 B<dirName> (a distinguished name),
206 and B<otherName>.
207 The syntax of each is described in the following paragraphs.
208
209 The B<email> option has a special C<copy> value, which will automatically
210 include any email addresses contained in the certificate subject name in
211 the extension.
212
213 The IP address used in the B<IP> option can be in either IPv4 or IPv6 format.
214
215 The value of B<dirName> is specifies the configuration section containing
216 the distinguished name to use, as a set of name-value pairs.
217 Multi-valued AVAs can be formed by prefacing the name with a B<+> character.
218
219 The value of B<otherName> can include arbitrary data associated with an OID;
220 the value should be the OID followed by a semicolon and the content in specified
221 using the syntax in L<ASN1_generate_nconf(3)>.
222
223 Examples:
224
225  subjectAltName = email:copy, email:my@other.address, URI:http://my.url.here/
226
227  subjectAltName = IP:192.168.7.1
228
229  subjectAltName = IP:13::17
230
231  subjectAltName = email:my@other.address, RID:1.2.3.4
232
233  subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
234
235  [extensions]
236  subjectAltName = dirName:dir_sect
237
238  [dir_sect]
239  C = UK
240  O = My Organization
241  OU = My Unit
242  CN = My Name
243
244 =head2 Issuer Alternative Name
245
246 This extension supports most of the options of subject alternative name;
247 it does not support B<email:copy>.
248 It also adds B<issuer:copy> as an allowed value, which copies any subject
249 alternative names from the issuer certificate, if possible.
250
251 Example:
252
253  issuerAltName = issuer:copy
254
255 =head2 Authority Info Access
256
257 This extension gives details about how to retrieve information that
258 related to the certificate that the CA makes available. The syntax is
259 B<access_id;location>, where B<access_id> is an object identifier
260 (although only a few values are well-known) and B<location> has the same
261 syntax as subject alternative name (except that B<email:copy> is not supported).
262
263 Examples:
264
265  authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
266
267 =head2 CRL distribution points
268
269 This is a multi-valued extension whose values can be either a name-value
270 pair using the same form as subject alternative name or a single value
271 specifying the section name containing all the distribution point values.
272
273 When a name-value pair is used, a DistributionPoint extension will
274 be set with the given value as the fullName field as the distributionPoint
275 value, and the reasons and cRLIssuer fields will be omitted.
276
277 When a single option is used, the value specifies the section, and that
278 section can have the following items:
279
280 =over 4
281
282 =item fullname
283
284 The full name of the distribution point, in the same format as the subject
285 alternative name.
286
287 =item relativename
288
289 The value is taken as a distinguished name fragment that is set as the
290 value of the nameRelativeToCRLIssuer field.
291
292 =item CRLIssuer
293
294 The value must in the same format as the subject alternative name.
295
296 =item reasons
297
298 A multi-value field that contains the reasons for revocation. The recognized
299 values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
300 C<superseded>, C<cessationOfOperation>, C<certificateHold>,
301 C<privilegeWithdrawn>, and C<AACompromise>.
302
303 =back
304
305 Only one of B<fullname> or B<relativename> should be specified.
306
307 Simple examples:
308
309  crlDistributionPoints = URI:http://myhost.com/myca.crl
310
311  crlDistributionPoints = URI:http://my.com/my.crl, URI:http://oth.com/my.crl
312
313 Full distribution point example:
314
315  [extensions]
316  crlDistributionPoints = crldp1_section
317
318  [crldp1_section]
319  fullname = URI:http://myhost.com/myca.crl
320  CRLissuer = dirName:issuer_sect
321  reasons = keyCompromise, CACompromise
322
323  [issuer_sect]
324  C = UK
325  O = Organisation
326  CN = Some Name
327
328 =head2 Issuing Distribution Point
329
330 This extension should only appear in CRLs. It is a multi-valued extension
331 whose syntax is similar to the "section" pointed to by the CRL distribution
332 points extension. The following names have meaning:
333
334 =over 4
335
336 =item fullname
337
338 The full name of the distribution point, in the same format as the subject
339 alternative name.
340
341 =item relativename
342
343 The value is taken as a distinguished name fragment that is set as the
344 value of the nameRelativeToCRLIssuer field.
345
346 =item onlysomereasons
347
348 A multi-value field that contains the reasons for revocation. The recognized
349 values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
350 C<superseded>, C<cessationOfOperation>, C<certificateHold>,
351 C<privilegeWithdrawn>, and C<AACompromise>.
352
353 =item onlyuser, onlyCA, onlyAA, indirectCRL
354
355 The value for each of these names is a boolean.
356
357 =back
358
359 Example:
360
361  [extensions]
362  issuingDistributionPoint = critical, @idp_section
363
364  [idp_section]
365  fullname = URI:http://myhost.com/myca.crl
366  indirectCRL = TRUE
367  onlysomereasons = keyCompromise, CACompromise
368
369 =head2 Certificate Policies
370
371 This is a I<raw> extension that supports all of the defined fields of the
372 certificate extension.
373
374 Policies without qualifiers are specified by giving the OID.
375 Multiple policies are comma-separated. For example:
376
377  certificatePolicies = 1.2.4.5, 1.1.3.4
378
379 To include policy qualifiers, use the "@section" syntax to point to a
380 section that specifies all the information.
381
382 The section referred to must include the policy OID using the name
383 B<policyIdentifier>. cPSuri qualifiers can be included using the syntax:
384
385  CPS.nnn = value
386
387 where C<nnn> is a number.
388
389 userNotice qualifiers can be set using the syntax:
390
391  userNotice.nnn = @notice
392
393 The value of the userNotice qualifier is specified in the relevant section.
394 This section can include B<explicitText>, B<organization>, and B<noticeNumbers>
395 options. explicitText and organization are text strings, noticeNumbers is a
396 comma separated list of numbers. The organization and noticeNumbers options
397 (if included) must BOTH be present. Some software might require
398 the B<ia5org> option at the top level; this changes the encoding from
399 Displaytext to IA5String.
400
401 Example:
402
403  [extensions]
404  certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect
405
406  [polsect]
407  policyIdentifier = 1.3.5.8
408  CPS.1 = "http://my.host.name/"
409  CPS.2 = "http://my.your.name/"
410  userNotice.1 = @notice
411
412  [notice]
413  explicitText = "Explicit Text Here"
414  organization = "Organisation Name"
415  noticeNumbers = 1, 2, 3, 4
416
417 The character encoding of explicitText can be specified by prefixing the
418 value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example:
419
420  [notice]
421  explicitText = "UTF8:Explicit Text Here"
422
423 =head2 Policy Constraints
424
425 This is a multi-valued extension which consisting of the names
426 B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
427 value. At least one component must be present.
428
429 Example:
430
431  policyConstraints = requireExplicitPolicy:3
432
433 =head2 Inhibit Any Policy
434
435 This is a string extension whose value must be a non negative integer.
436
437 Example:
438
439  inhibitAnyPolicy = 2
440
441 =head2 Name Constraints
442
443 This is a multi-valued extension. The name should
444 begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
445 the name and the value follows the syntax of subjectAltName except
446 B<email:copy>
447 is not supported and the B<IP> form should consist of an IP addresses and
448 subnet mask separated by a B</>.
449
450 Examples:
451
452  nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
453
454  nameConstraints = permitted;email:.somedomain.com
455
456  nameConstraints = excluded;email:.com
457
458 =head2 OCSP No Check
459
460 This is a string extension. It is parsed, but ignored.
461
462 Example:
463
464  noCheck = ignored
465
466 =head2 TLS Feature (aka Must Staple)
467
468 This is a multi-valued extension consisting of a list of TLS extension
469 identifiers. Each identifier may be a number (0..65535) or a supported name.
470 When a TLS client sends a listed extension, the TLS server is expected to
471 include that extension in its reply.
472
473 The supported names are: B<status_request> and B<status_request_v2>.
474
475 Example:
476
477  tlsfeature = status_request
478
479 =head1 DEPRECATED EXTENSIONS
480
481 The following extensions are non standard, Netscape specific and largely
482 obsolete. Their use in new applications is discouraged.
483
484 =head2 Netscape String extensions
485
486 Netscape Comment (B<nsComment>) is a string extension containing a comment
487 which will be displayed when the certificate is viewed in some browsers.
488 Other extensions of this type are: B<nsBaseUrl>,
489 B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
490 and B<nsSslServerName>.
491
492 =head2 Netscape Certificate Type
493
494 This is a multi-valued extensions which consists of a list of flags to be
495 included. It was used to indicate the purposes for which a certificate could
496 be used. The basicConstraints, keyUsage and extended key usage extensions are
497 now used instead.
498
499 Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
500 B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
501
502 =head1 ARBITRARY EXTENSIONS
503
504 If an extension is not supported by the OpenSSL code then it must be encoded
505 using the arbitrary extension format. It is also possible to use the arbitrary
506 format for supported extensions. Extreme care should be taken to ensure that
507 the data is formatted correctly for the given extension type.
508
509 There are two ways to encode arbitrary extensions.
510
511 The first way is to use the word ASN1 followed by the extension content
512 using the same syntax as L<ASN1_generate_nconf(3)>.
513 For example:
514
515  [extensions]
516  1.2.3.4 = critical, ASN1:UTF8String:Some random data
517  1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
518
519  [seq_sect]
520  field1 = UTF8:field1
521  field2 = UTF8:field2
522
523 It is also possible to use the word DER to include the raw encoded data in any
524 extension.
525
526  1.2.3.4 = critical, DER:01:02:03:04
527  1.2.3.4.1 = DER:01020304
528
529 The value following DER is a hex dump of the DER encoding of the extension
530 Any extension can be placed in this form to override the default behaviour.
531 For example:
532
533  basicConstraints = critical, DER:00:01:02:03
534
535 =head1 WARNINGS
536
537 There is no guarantee that a specific implementation will process a given
538 extension. It may therefore be sometimes possible to use certificates for
539 purposes prohibited by their extensions because a specific application does
540 not recognize or honour the values of the relevant extensions.
541
542 The DER and ASN1 options should be used with caution. It is possible to create
543 invalid extensions if they are not used carefully.
544
545 =head1 SEE ALSO
546
547 L<openssl-req(1)>, L<openssl-ca(1)>, L<openssl-x509(1)>,
548 L<ASN1_generate_nconf(3)>
549
550 =head1 COPYRIGHT
551
552 Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.
553
554 Licensed under the Apache License 2.0 (the "License").  You may not use
555 this file except in compliance with the License.  You can obtain a copy
556 in the file LICENSE in the source distribution or at
557 L<https://www.openssl.org/source/license.html>.
558
559 =cut