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