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 comma-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 occurrences 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