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