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 documented. 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. 176 177=over 4 178 179=item B<none> 180 181No SKID extension will be included. 182 183=item B<hash> 184 185The process specified in RFC 5280 section 4.2.1.2. (1) is followed: 186The keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the BIT 187STRING subjectPublicKey (excluding the tag, length, and number of unused bits). 188 189=item A hex string (possibly with C<:> separating bytes) 190 191The provided value is output directly. 192This choice is strongly discouraged. 193 194=back 195 196By default the B<x509>, B<req>, and B<ca> apps behave as if B<hash> was given. 197 198Example: 199 200 subjectKeyIdentifier = hash 201 202=head2 Authority Key Identifier 203 204The AKID extension specification may have the value B<none> 205indicating that no AKID shall be included. 206Otherwise it may have the value B<keyid> or B<issuer> 207or both of them, separated by C<,>. 208Either or both can have the option B<always>, 209indicated by putting a colon C<:> between the value and this option. 210For self-signed certificates the AKID is suppressed unless B<always> is present. 211 212By default the B<x509>, B<req>, and B<ca> apps behave as if B<none> was given 213for self-signed certificates and B<keyid>C<,> B<issuer> otherwise. 214 215If B<keyid> is present, an attempt is made to 216copy the subject key identifier (SKID) from the issuer certificate except if 217the issuer certificate is the same as the current one and it is not self-signed. 218The hash of the public key related to the signing key is taken as fallback 219if the issuer certificate is the same as the current certificate. 220If B<always> is present but no value can be obtained, an error is returned. 221 222If B<issuer> is present, and in addition it has the option B<always> specified 223or B<keyid> is not present, 224then the issuer DN and serial number are copied from the issuer certificate. 225If this fails, an error is returned. 226 227Examples: 228 229 authorityKeyIdentifier = keyid, issuer 230 231 authorityKeyIdentifier = keyid, issuer:always 232 233=head2 Subject Alternative Name 234 235This is a multi-valued extension that supports several types of name 236identifier, including 237B<email> (an email address), 238B<URI> (a uniform resource indicator), 239B<DNS> (a DNS domain name), 240B<RID> (a registered ID: OBJECT IDENTIFIER), 241B<IP> (an IP address), 242B<dirName> (a distinguished name), 243and B<otherName>. 244The syntax of each is described in the following paragraphs. 245 246The B<email> option has two special values. 247C<copy> will automatically include any email addresses 248contained in the certificate subject name in the extension. 249C<move> will automatically move any email addresses 250from the certificate subject name to the extension. 251 252The IP address used in the B<IP> option can be in either IPv4 or IPv6 format. 253 254The value of B<dirName> is specifies the configuration section containing 255the distinguished name to use, as a set of name-value pairs. 256Multi-valued AVAs can be formed by prefacing the name with a B<+> character. 257 258The value of B<otherName> can include arbitrary data associated with an OID; 259the value should be the OID followed by a semicolon and the content in specified 260using the syntax in L<ASN1_generate_nconf(3)>. 261 262Examples: 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 283Non-ASCII Email Address conforming the syntax defined in Section 3.3 of RFC 6531 284are provided as otherName.SmtpUTF8Mailbox. According to RFC 8398, the email 285address should be provided as UTF8String. To enforce the valid representation in 286the 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 294This extension supports most of the options of subject alternative name; 295it does not support B<email:copy>. 296It also adds B<issuer:copy> as an allowed value, which copies any subject 297alternative names from the issuer certificate, if possible. 298 299Example: 300 301 issuerAltName = issuer:copy 302 303=head2 Authority Info Access 304 305This extension gives details about how to retrieve information that 306related to the certificate that the CA makes available. The syntax is 307B<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 309syntax as subject alternative name (except that B<email:copy> is not supported). 310 311Possible values for access_id include B<OCSP> (OCSP responder), 312B<caIssuers> (CA Issuers), 313B<ad_timestamping> (AD Time Stamping), 314B<AD_DVCS> (ad dvcs), 315B<caRepository> (CA Repository). 316 317Examples: 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 325This is a multi-valued extension whose values can be either a name-value 326pair using the same form as subject alternative name or a single value 327specifying the section name containing all the distribution point values. 328 329When a name-value pair is used, a DistributionPoint extension will 330be set with the given value as the fullName field as the distributionPoint 331value, and the reasons and cRLIssuer fields will be omitted. 332 333When a single option is used, the value specifies the section, and that 334section can have the following items: 335 336=over 4 337 338=item fullname 339 340The full name of the distribution point, in the same format as the subject 341alternative name. 342 343=item relativename 344 345The value is taken as a distinguished name fragment that is set as the 346value of the nameRelativeToCRLIssuer field. 347 348=item CRLIssuer 349 350The value must in the same format as the subject alternative name. 351 352=item reasons 353 354A multi-value field that contains the reasons for revocation. The recognized 355values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>, 356C<superseded>, C<cessationOfOperation>, C<certificateHold>, 357C<privilegeWithdrawn>, and C<AACompromise>. 358 359=back 360 361Only one of B<fullname> or B<relativename> should be specified. 362 363Simple 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 369Full 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 386This extension should only appear in CRLs. It is a multi-valued extension 387whose syntax is similar to the "section" pointed to by the CRL distribution 388points extension. The following names have meaning: 389 390=over 4 391 392=item fullname 393 394The full name of the distribution point, in the same format as the subject 395alternative name. 396 397=item relativename 398 399The value is taken as a distinguished name fragment that is set as the 400value of the nameRelativeToCRLIssuer field. 401 402=item onlysomereasons 403 404A multi-value field that contains the reasons for revocation. The recognized 405values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>, 406C<superseded>, C<cessationOfOperation>, C<certificateHold>, 407C<privilegeWithdrawn>, and C<AACompromise>. 408 409=item onlyuser, onlyCA, onlyAA, indirectCRL 410 411The value for each of these names is a boolean. 412 413=back 414 415Example: 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 427This is a I<raw> extension that supports all of the defined fields of the 428certificate extension. 429 430Policies without qualifiers are specified by giving the OID. 431Multiple policies are comma-separated. For example: 432 433 certificatePolicies = 1.2.4.5, 1.1.3.4 434 435To include policy qualifiers, use the "@section" syntax to point to a 436section that specifies all the information. 437 438The section referred to must include the policy OID using the name 439B<policyIdentifier>. cPSuri qualifiers can be included using the syntax: 440 441 CPS.nnn = value 442 443where C<nnn> is a number. 444 445userNotice qualifiers can be set using the syntax: 446 447 userNotice.nnn = @notice 448 449The value of the userNotice qualifier is specified in the relevant section. 450This section can include B<explicitText>, B<organization>, and B<noticeNumbers> 451options. explicitText and organization are text strings, noticeNumbers is a 452comma separated list of numbers. The organization and noticeNumbers options 453(if included) must BOTH be present. Some software might require 454the B<ia5org> option at the top level; this changes the encoding from 455Displaytext to IA5String. 456 457Example: 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 473The character encoding of explicitText can be specified by prefixing the 474value 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 481This is a multi-valued extension which consisting of the names 482B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer 483value. At least one component must be present. 484 485Example: 486 487 policyConstraints = requireExplicitPolicy:3 488 489=head2 Inhibit Any Policy 490 491This is a string extension whose value must be a non negative integer. 492 493Example: 494 495 inhibitAnyPolicy = 2 496 497=head2 Name Constraints 498 499This is a multi-valued extension. The name should 500begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of 501the name and the value follows the syntax of subjectAltName except 502B<email:copy> 503is not supported and the B<IP> form should consist of an IP addresses and 504subnet mask separated by a B</>. 505 506Examples: 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 516This is a string extension. It is parsed, but ignored. 517 518Example: 519 520 noCheck = ignored 521 522=head2 TLS Feature (aka Must Staple) 523 524This is a multi-valued extension consisting of a list of TLS extension 525identifiers. Each identifier may be a number (0..65535) or a supported name. 526When a TLS client sends a listed extension, the TLS server is expected to 527include that extension in its reply. 528 529The supported names are: B<status_request> and B<status_request_v2>. 530 531Example: 532 533 tlsfeature = status_request 534 535=head1 DEPRECATED EXTENSIONS 536 537The following extensions are non standard, Netscape specific and largely 538obsolete. Their use in new applications is discouraged. 539 540=head2 Netscape String extensions 541 542Netscape Comment (B<nsComment>) is a string extension containing a comment 543which will be displayed when the certificate is viewed in some browsers. 544Other extensions of this type are: B<nsBaseUrl>, 545B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> 546and B<nsSslServerName>. 547 548=head2 Netscape Certificate Type 549 550This is a multi-valued extensions which consists of a list of flags to be 551included. It was used to indicate the purposes for which a certificate could 552be used. The basicConstraints, keyUsage and extended key usage extensions are 553now used instead. 554 555Acceptable values for nsCertType are: B<client>, B<server>, B<email>, 556B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. 557 558=head1 ARBITRARY EXTENSIONS 559 560If an extension is not supported by the OpenSSL code then it must be encoded 561using the arbitrary extension format. It is also possible to use the arbitrary 562format for supported extensions. Extreme care should be taken to ensure that 563the data is formatted correctly for the given extension type. 564 565There are two ways to encode arbitrary extensions. 566 567The first way is to use the word ASN1 followed by the extension content 568using the same syntax as L<ASN1_generate_nconf(3)>. 569For 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 579It is also possible to use the word DER to include the raw encoded data in any 580extension. 581 582 1.2.3.4 = critical, DER:01:02:03:04 583 1.2.3.4.1 = DER:01020304 584 585The value following DER is a hex dump of the DER encoding of the extension 586Any extension can be placed in this form to override the default behaviour. 587For example: 588 589 basicConstraints = critical, DER:00:01:02:03 590 591=head1 WARNINGS 592 593There is no guarantee that a specific implementation will process a given 594extension. It may therefore be sometimes possible to use certificates for 595purposes prohibited by their extensions because a specific application does 596not recognize or honour the values of the relevant extensions. 597 598The DER and ASN1 options should be used with caution. It is possible to create 599invalid extensions if they are not used carefully. 600 601=head1 SEE ALSO 602 603L<openssl-req(1)>, L<openssl-ca(1)>, L<openssl-x509(1)>, 604L<ASN1_generate_nconf(3)> 605 606=head1 COPYRIGHT 607 608Copyright 2004-2023 The OpenSSL Project Authors. All Rights Reserved. 609 610Licensed under the Apache License 2.0 (the "License"). You may not use 611this file except in compliance with the License. You can obtain a copy 612in the file LICENSE in the source distribution or at 613L<https://www.openssl.org/source/license.html>. 614 615=cut 616