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