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. 197By default the B<x509>, B<req>, and B<ca> apps behave as if 198"none" was given for self-signed certificates and "keyid, issuer" otherwise. 199 200If B<keyid> is present, an attempt is made to compute the hash of the public key 201corresponding to the signing key in case the certificate is self-signed, 202or else to copy the subject key identifier (SKID) from the issuer certificate. 203If this fails and the option B<always> is present, an error is returned. 204 205If B<issuer> is present, and in addition it has the option B<always> specified 206or B<keyid> is not present, 207then the issuer DN and serial number are copied from the issuer certificate. 208 209Examples: 210 211 authorityKeyIdentifier = keyid, issuer 212 213 authorityKeyIdentifier = keyid, issuer:always 214 215=head2 Subject Alternative Name 216 217This is a multi-valued extension that supports several types of name 218identifier, including 219B<email> (an email address), 220B<URI> (a uniform resource indicator), 221B<DNS> (a DNS domain name), 222B<RID> (a registered ID: OBJECT IDENTIFIER), 223B<IP> (an IP address), 224B<dirName> (a distinguished name), 225and B<otherName>. 226The syntax of each is described in the following paragraphs. 227 228The B<email> option has a special C<copy> value, which will automatically 229include any email addresses contained in the certificate subject name in 230the extension. 231 232The IP address used in the B<IP> option can be in either IPv4 or IPv6 format. 233 234The value of B<dirName> is specifies the configuration section containing 235the distinguished name to use, as a set of name-value pairs. 236Multi-valued AVAs can be formed by prefacing the name with a B<+> character. 237 238The value of B<otherName> can include arbitrary data associated with an OID; 239the value should be the OID followed by a semicolon and the content in specified 240using the syntax in L<ASN1_generate_nconf(3)>. 241 242Examples: 243 244 subjectAltName = email:copy, email:my@example.com, URI:http://my.example.com/ 245 246 subjectAltName = IP:192.168.7.1 247 248 subjectAltName = IP:13::17 249 250 subjectAltName = email:my@example.com, RID:1.2.3.4 251 252 subjectAltName = otherName:1.2.3.4;UTF8:some other identifier 253 254 [extensions] 255 subjectAltName = dirName:dir_sect 256 257 [dir_sect] 258 C = UK 259 O = My Organization 260 OU = My Unit 261 CN = My Name 262 263Non-ASCII Email Address conforming the syntax defined in Section 3.3 of RFC 6531 264are provided as otherName.SmtpUTF8Mailbox. According to RFC 8398, the email 265address should be provided as UTF8String. To enforce the valid representation in 266the certificate, the SmtpUTF8Mailbox should be provided as follows 267 268 subjectAltName=@alts 269 [alts] 270 otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com 271 272=head2 Issuer Alternative Name 273 274This extension supports most of the options of subject alternative name; 275it does not support B<email:copy>. 276It also adds B<issuer:copy> as an allowed value, which copies any subject 277alternative names from the issuer certificate, if possible. 278 279Example: 280 281 issuerAltName = issuer:copy 282 283=head2 Authority Info Access 284 285This extension gives details about how to retrieve information that 286related to the certificate that the CA makes available. The syntax is 287B<access_id;location>, where B<access_id> is an object identifier 288(although only a few values are well-known) and B<location> has the same 289syntax as subject alternative name (except that B<email:copy> is not supported). 290 291Possible values for access_id include B<OCSP> (OCSP responder), 292B<caIssuers> (CA Issuers), 293B<ad_timestamping> (AD Time Stamping), 294B<AD_DVCS> (ad dvcs), 295B<caRepository> (CA Repository). 296 297Examples: 298 299 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer 300 301 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/ 302 303=head2 CRL distribution points 304 305This is a multi-valued extension whose values can be either a name-value 306pair using the same form as subject alternative name or a single value 307specifying the section name containing all the distribution point values. 308 309When a name-value pair is used, a DistributionPoint extension will 310be set with the given value as the fullName field as the distributionPoint 311value, and the reasons and cRLIssuer fields will be omitted. 312 313When a single option is used, the value specifies the section, and that 314section can have the following items: 315 316=over 4 317 318=item fullname 319 320The full name of the distribution point, in the same format as the subject 321alternative name. 322 323=item relativename 324 325The value is taken as a distinguished name fragment that is set as the 326value of the nameRelativeToCRLIssuer field. 327 328=item CRLIssuer 329 330The value must in the same format as the subject alternative name. 331 332=item reasons 333 334A multi-value field that contains the reasons for revocation. The recognized 335values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>, 336C<superseded>, C<cessationOfOperation>, C<certificateHold>, 337C<privilegeWithdrawn>, and C<AACompromise>. 338 339=back 340 341Only one of B<fullname> or B<relativename> should be specified. 342 343Simple examples: 344 345 crlDistributionPoints = URI:http://example.com/myca.crl 346 347 crlDistributionPoints = URI:http://example.com/myca.crl, URI:http://example.org/my.crl 348 349Full distribution point example: 350 351 [extensions] 352 crlDistributionPoints = crldp1_section 353 354 [crldp1_section] 355 fullname = URI:http://example.com/myca.crl 356 CRLissuer = dirName:issuer_sect 357 reasons = keyCompromise, CACompromise 358 359 [issuer_sect] 360 C = UK 361 O = Organisation 362 CN = Some Name 363 364=head2 Issuing Distribution Point 365 366This extension should only appear in CRLs. It is a multi-valued extension 367whose syntax is similar to the "section" pointed to by the CRL distribution 368points extension. The following names have meaning: 369 370=over 4 371 372=item fullname 373 374The full name of the distribution point, in the same format as the subject 375alternative name. 376 377=item relativename 378 379The value is taken as a distinguished name fragment that is set as the 380value of the nameRelativeToCRLIssuer field. 381 382=item onlysomereasons 383 384A multi-value field that contains the reasons for revocation. The recognized 385values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>, 386C<superseded>, C<cessationOfOperation>, C<certificateHold>, 387C<privilegeWithdrawn>, and C<AACompromise>. 388 389=item onlyuser, onlyCA, onlyAA, indirectCRL 390 391The value for each of these names is a boolean. 392 393=back 394 395Example: 396 397 [extensions] 398 issuingDistributionPoint = critical, @idp_section 399 400 [idp_section] 401 fullname = URI:http://example.com/myca.crl 402 indirectCRL = TRUE 403 onlysomereasons = keyCompromise, CACompromise 404 405=head2 Certificate Policies 406 407This is a I<raw> extension that supports all of the defined fields of the 408certificate extension. 409 410Policies without qualifiers are specified by giving the OID. 411Multiple policies are comma-separated. For example: 412 413 certificatePolicies = 1.2.4.5, 1.1.3.4 414 415To include policy qualifiers, use the "@section" syntax to point to a 416section that specifies all the information. 417 418The section referred to must include the policy OID using the name 419B<policyIdentifier>. cPSuri qualifiers can be included using the syntax: 420 421 CPS.nnn = value 422 423where C<nnn> is a number. 424 425userNotice qualifiers can be set using the syntax: 426 427 userNotice.nnn = @notice 428 429The value of the userNotice qualifier is specified in the relevant section. 430This section can include B<explicitText>, B<organization>, and B<noticeNumbers> 431options. explicitText and organization are text strings, noticeNumbers is a 432comma separated list of numbers. The organization and noticeNumbers options 433(if included) must BOTH be present. Some software might require 434the B<ia5org> option at the top level; this changes the encoding from 435Displaytext to IA5String. 436 437Example: 438 439 [extensions] 440 certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect 441 442 [polsect] 443 policyIdentifier = 1.3.5.8 444 CPS.1 = "http://my.host.example.com/" 445 CPS.2 = "http://my.your.example.com/" 446 userNotice.1 = @notice 447 448 [notice] 449 explicitText = "Explicit Text Here" 450 organization = "Organisation Name" 451 noticeNumbers = 1, 2, 3, 4 452 453The character encoding of explicitText can be specified by prefixing the 454value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example: 455 456 [notice] 457 explicitText = "UTF8:Explicit Text Here" 458 459=head2 Policy Constraints 460 461This is a multi-valued extension which consisting of the names 462B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer 463value. At least one component must be present. 464 465Example: 466 467 policyConstraints = requireExplicitPolicy:3 468 469=head2 Inhibit Any Policy 470 471This is a string extension whose value must be a non negative integer. 472 473Example: 474 475 inhibitAnyPolicy = 2 476 477=head2 Name Constraints 478 479This is a multi-valued extension. The name should 480begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of 481the name and the value follows the syntax of subjectAltName except 482B<email:copy> 483is not supported and the B<IP> form should consist of an IP addresses and 484subnet mask separated by a B</>. 485 486Examples: 487 488 nameConstraints = permitted;IP:192.168.0.0/255.255.0.0 489 490 nameConstraints = permitted;email:.example.com 491 492 nameConstraints = excluded;email:.com 493 494=head2 OCSP No Check 495 496This is a string extension. It is parsed, but ignored. 497 498Example: 499 500 noCheck = ignored 501 502=head2 TLS Feature (aka Must Staple) 503 504This is a multi-valued extension consisting of a list of TLS extension 505identifiers. Each identifier may be a number (0..65535) or a supported name. 506When a TLS client sends a listed extension, the TLS server is expected to 507include that extension in its reply. 508 509The supported names are: B<status_request> and B<status_request_v2>. 510 511Example: 512 513 tlsfeature = status_request 514 515=head1 DEPRECATED EXTENSIONS 516 517The following extensions are non standard, Netscape specific and largely 518obsolete. Their use in new applications is discouraged. 519 520=head2 Netscape String extensions 521 522Netscape Comment (B<nsComment>) is a string extension containing a comment 523which will be displayed when the certificate is viewed in some browsers. 524Other extensions of this type are: B<nsBaseUrl>, 525B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> 526and B<nsSslServerName>. 527 528=head2 Netscape Certificate Type 529 530This is a multi-valued extensions which consists of a list of flags to be 531included. It was used to indicate the purposes for which a certificate could 532be used. The basicConstraints, keyUsage and extended key usage extensions are 533now used instead. 534 535Acceptable values for nsCertType are: B<client>, B<server>, B<email>, 536B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. 537 538=head1 ARBITRARY EXTENSIONS 539 540If an extension is not supported by the OpenSSL code then it must be encoded 541using the arbitrary extension format. It is also possible to use the arbitrary 542format for supported extensions. Extreme care should be taken to ensure that 543the data is formatted correctly for the given extension type. 544 545There are two ways to encode arbitrary extensions. 546 547The first way is to use the word ASN1 followed by the extension content 548using the same syntax as L<ASN1_generate_nconf(3)>. 549For example: 550 551 [extensions] 552 1.2.3.4 = critical, ASN1:UTF8String:Some random data 553 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect 554 555 [seq_sect] 556 field1 = UTF8:field1 557 field2 = UTF8:field2 558 559It is also possible to use the word DER to include the raw encoded data in any 560extension. 561 562 1.2.3.4 = critical, DER:01:02:03:04 563 1.2.3.4.1 = DER:01020304 564 565The value following DER is a hex dump of the DER encoding of the extension 566Any extension can be placed in this form to override the default behaviour. 567For example: 568 569 basicConstraints = critical, DER:00:01:02:03 570 571=head1 WARNINGS 572 573There is no guarantee that a specific implementation will process a given 574extension. It may therefore be sometimes possible to use certificates for 575purposes prohibited by their extensions because a specific application does 576not recognize or honour the values of the relevant extensions. 577 578The DER and ASN1 options should be used with caution. It is possible to create 579invalid extensions if they are not used carefully. 580 581=head1 SEE ALSO 582 583L<openssl-req(1)>, L<openssl-ca(1)>, L<openssl-x509(1)>, 584L<ASN1_generate_nconf(3)> 585 586=head1 COPYRIGHT 587 588Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved. 589 590Licensed under the Apache License 2.0 (the "License"). You may not use 591this file except in compliance with the License. You can obtain a copy 592in the file LICENSE in the source distribution or at 593L<https://www.openssl.org/source/license.html>. 594 595=cut 596