5 x509v3_config - X509 V3 certificate extension configuration format
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.
17 This page uses B<extensions> as the name of the section, when needed
20 Each entry in the extension section takes the form:
22 name = [critical, ]value(s)
24 If B<critical> is present then the extension will be marked as critical.
26 If multiple entries are processed for the same extension name,
27 later entries override earlier ones with the same name.
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:
38 Each is described in the following paragraphs.
40 String extensions simply have a string which contains either the value itself
41 or how it is obtained.
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:
46 basicConstraints = critical, CA:true, pathlen:1
48 The long form allows the values to be placed in a separate section:
51 basicConstraints = critical, @basic_constraints
57 Both forms are equivalent.
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:
63 subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
65 will produce an error but the equivalent form:
68 subjectAltName = @subject_alt_section
71 subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
75 OpenSSL does not support multiple occurrences of the same field within a
76 section. In this example:
79 subjectAltName = @alt_section
82 email = steve@example.com
83 email = steve@example.org
85 will only recognize the last value. To specify multiple values append a
86 numeric identifier, as shown here:
89 subjectAltName = @alt_section
92 email.1 = steve@example.com
93 email.2 = steve@example.org
95 The syntax of raw extensions is defined by the source code that parses
96 the extension but should be documened.
97 See L</Certificate Policies> for an example of a raw extension.
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.
102 =head1 STANDARD EXTENSIONS
104 The following sections describe the syntax of each supported extension.
105 They do not define the semantics of the extension.
107 =head2 Basic Constraints
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.
116 basicConstraints = CA:TRUE
118 basicConstraints = CA:FALSE
120 basicConstraints = critical, CA:TRUE, pathlen:1
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.
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>.
138 keyUsage = digitalSignature, nonRepudiation
140 keyUsage = critical, keyCertSign
142 =head2 Extended Key Usage
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:
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
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.
169 extendedKeyUsage = critical, codeSigning, 1.2.3.4
171 extendedKeyUsage = serverAuth, clientAuth
173 =head2 Subject Key Identifier
175 The SKID extension specification has a value with three choices.
176 If the value is the word B<none> then no SKID extension will be included.
177 If the value is the word B<hash>, or by default for the B<x509>, B<req>, and
178 B<ca> apps, the process specified in RFC 5280 section 4.2.1.2. (1) is followed:
179 The keyIdentifier is composed of the 160-bit SHA-1 hash of the value of the BIT
180 STRING subjectPublicKey (excluding the tag, length, and number of unused bits).
182 Otherwise, the value must be a hex string (possibly with C<:> separating bytes)
183 to output directly, however, this is strongly discouraged.
187 subjectKeyIdentifier = hash
189 =head2 Authority Key Identifier
191 The AKID extension specification may have the value B<none>
192 indicating that no AKID shall be included.
193 Otherwise it may have the value B<keyid> or B<issuer>
194 or both of them, separated by C<,>.
195 Either or both can have the option B<always>,
196 indicated by putting a colon C<:> between the value and this option.
197 For self-signed certificates the AKID is suppressed unless B<always> is present.
198 By 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.
201 If B<keyid> is present, an attempt is made to
202 copy the subject key identifier (SKID) from the issuer certificate except if
203 the issuer certificate is the same as the current one and it is not self-signed.
204 The hash of the public key related to the signing key is taken as fallback
205 if the issuer certificate is the same as the current certificate.
206 If B<always> is present but no value can be obtained, an error is returned.
208 If B<issuer> is present, and in addition it has the option B<always> specified
209 or B<keyid> is not present,
210 then the issuer DN and serial number are copied from the issuer certificate.
211 If this fails, an error is returned.
215 authorityKeyIdentifier = keyid, issuer
217 authorityKeyIdentifier = keyid, issuer:always
219 =head2 Subject Alternative Name
221 This is a multi-valued extension that supports several types of name
222 identifier, including
223 B<email> (an email address),
224 B<URI> (a uniform resource indicator),
225 B<DNS> (a DNS domain name),
226 B<RID> (a registered ID: OBJECT IDENTIFIER),
227 B<IP> (an IP address),
228 B<dirName> (a distinguished name),
230 The syntax of each is described in the following paragraphs.
232 The B<email> option has two special values.
233 C<copy> will automatically include any email addresses
234 contained in the certificate subject name in the extension.
235 C<move> will automatically move any email addresses
236 from the certificate subject name to the extension.
238 The IP address used in the B<IP> option can be in either IPv4 or IPv6 format.
240 The value of B<dirName> is specifies the configuration section containing
241 the distinguished name to use, as a set of name-value pairs.
242 Multi-valued AVAs can be formed by prefacing the name with a B<+> character.
244 The value of B<otherName> can include arbitrary data associated with an OID;
245 the value should be the OID followed by a semicolon and the content in specified
246 using the syntax in L<ASN1_generate_nconf(3)>.
250 subjectAltName = email:copy, email:my@example.com, URI:http://my.example.com/
252 subjectAltName = IP:192.168.7.1
254 subjectAltName = IP:13::17
256 subjectAltName = email:my@example.com, RID:1.2.3.4
258 subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
261 subjectAltName = dirName:dir_sect
269 Non-ASCII Email Address conforming the syntax defined in Section 3.3 of RFC 6531
270 are provided as otherName.SmtpUTF8Mailbox. According to RFC 8398, the email
271 address should be provided as UTF8String. To enforce the valid representation in
272 the certificate, the SmtpUTF8Mailbox should be provided as follows
276 otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com
278 =head2 Issuer Alternative Name
280 This extension supports most of the options of subject alternative name;
281 it does not support B<email:copy>.
282 It also adds B<issuer:copy> as an allowed value, which copies any subject
283 alternative names from the issuer certificate, if possible.
287 issuerAltName = issuer:copy
289 =head2 Authority Info Access
291 This extension gives details about how to retrieve information that
292 related to the certificate that the CA makes available. The syntax is
293 B<access_id;location>, where B<access_id> is an object identifier
294 (although only a few values are well-known) and B<location> has the same
295 syntax as subject alternative name (except that B<email:copy> is not supported).
297 Possible values for access_id include B<OCSP> (OCSP responder),
298 B<caIssuers> (CA Issuers),
299 B<ad_timestamping> (AD Time Stamping),
300 B<AD_DVCS> (ad dvcs),
301 B<caRepository> (CA Repository).
305 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer
307 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/
309 =head2 CRL distribution points
311 This is a multi-valued extension whose values can be either a name-value
312 pair using the same form as subject alternative name or a single value
313 specifying the section name containing all the distribution point values.
315 When a name-value pair is used, a DistributionPoint extension will
316 be set with the given value as the fullName field as the distributionPoint
317 value, and the reasons and cRLIssuer fields will be omitted.
319 When a single option is used, the value specifies the section, and that
320 section can have the following items:
326 The full name of the distribution point, in the same format as the subject
331 The value is taken as a distinguished name fragment that is set as the
332 value of the nameRelativeToCRLIssuer field.
336 The value must in the same format as the subject alternative name.
340 A multi-value field that contains the reasons for revocation. The recognized
341 values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
342 C<superseded>, C<cessationOfOperation>, C<certificateHold>,
343 C<privilegeWithdrawn>, and C<AACompromise>.
347 Only one of B<fullname> or B<relativename> should be specified.
351 crlDistributionPoints = URI:http://example.com/myca.crl
353 crlDistributionPoints = URI:http://example.com/myca.crl, URI:http://example.org/my.crl
355 Full distribution point example:
358 crlDistributionPoints = crldp1_section
361 fullname = URI:http://example.com/myca.crl
362 CRLissuer = dirName:issuer_sect
363 reasons = keyCompromise, CACompromise
370 =head2 Issuing Distribution Point
372 This extension should only appear in CRLs. It is a multi-valued extension
373 whose syntax is similar to the "section" pointed to by the CRL distribution
374 points extension. The following names have meaning:
380 The full name of the distribution point, in the same format as the subject
385 The value is taken as a distinguished name fragment that is set as the
386 value of the nameRelativeToCRLIssuer field.
388 =item onlysomereasons
390 A multi-value field that contains the reasons for revocation. The recognized
391 values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
392 C<superseded>, C<cessationOfOperation>, C<certificateHold>,
393 C<privilegeWithdrawn>, and C<AACompromise>.
395 =item onlyuser, onlyCA, onlyAA, indirectCRL
397 The value for each of these names is a boolean.
404 issuingDistributionPoint = critical, @idp_section
407 fullname = URI:http://example.com/myca.crl
409 onlysomereasons = keyCompromise, CACompromise
411 =head2 Certificate Policies
413 This is a I<raw> extension that supports all of the defined fields of the
414 certificate extension.
416 Policies without qualifiers are specified by giving the OID.
417 Multiple policies are comma-separated. For example:
419 certificatePolicies = 1.2.4.5, 1.1.3.4
421 To include policy qualifiers, use the "@section" syntax to point to a
422 section that specifies all the information.
424 The section referred to must include the policy OID using the name
425 B<policyIdentifier>. cPSuri qualifiers can be included using the syntax:
429 where C<nnn> is a number.
431 userNotice qualifiers can be set using the syntax:
433 userNotice.nnn = @notice
435 The value of the userNotice qualifier is specified in the relevant section.
436 This section can include B<explicitText>, B<organization>, and B<noticeNumbers>
437 options. explicitText and organization are text strings, noticeNumbers is a
438 comma separated list of numbers. The organization and noticeNumbers options
439 (if included) must BOTH be present. Some software might require
440 the B<ia5org> option at the top level; this changes the encoding from
441 Displaytext to IA5String.
446 certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect
449 policyIdentifier = 1.3.5.8
450 CPS.1 = "http://my.host.example.com/"
451 CPS.2 = "http://my.your.example.com/"
452 userNotice.1 = @notice
455 explicitText = "Explicit Text Here"
456 organization = "Organisation Name"
457 noticeNumbers = 1, 2, 3, 4
459 The character encoding of explicitText can be specified by prefixing the
460 value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example:
463 explicitText = "UTF8:Explicit Text Here"
465 =head2 Policy Constraints
467 This is a multi-valued extension which consisting of the names
468 B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
469 value. At least one component must be present.
473 policyConstraints = requireExplicitPolicy:3
475 =head2 Inhibit Any Policy
477 This is a string extension whose value must be a non negative integer.
483 =head2 Name Constraints
485 This is a multi-valued extension. The name should
486 begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
487 the name and the value follows the syntax of subjectAltName except
489 is not supported and the B<IP> form should consist of an IP addresses and
490 subnet mask separated by a B</>.
494 nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
496 nameConstraints = permitted;email:.example.com
498 nameConstraints = excluded;email:.com
502 This is a string extension. It is parsed, but ignored.
508 =head2 TLS Feature (aka Must Staple)
510 This is a multi-valued extension consisting of a list of TLS extension
511 identifiers. Each identifier may be a number (0..65535) or a supported name.
512 When a TLS client sends a listed extension, the TLS server is expected to
513 include that extension in its reply.
515 The supported names are: B<status_request> and B<status_request_v2>.
519 tlsfeature = status_request
521 =head1 DEPRECATED EXTENSIONS
523 The following extensions are non standard, Netscape specific and largely
524 obsolete. Their use in new applications is discouraged.
526 =head2 Netscape String extensions
528 Netscape Comment (B<nsComment>) is a string extension containing a comment
529 which will be displayed when the certificate is viewed in some browsers.
530 Other extensions of this type are: B<nsBaseUrl>,
531 B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
532 and B<nsSslServerName>.
534 =head2 Netscape Certificate Type
536 This is a multi-valued extensions which consists of a list of flags to be
537 included. It was used to indicate the purposes for which a certificate could
538 be used. The basicConstraints, keyUsage and extended key usage extensions are
541 Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
542 B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
544 =head1 ARBITRARY EXTENSIONS
546 If an extension is not supported by the OpenSSL code then it must be encoded
547 using the arbitrary extension format. It is also possible to use the arbitrary
548 format for supported extensions. Extreme care should be taken to ensure that
549 the data is formatted correctly for the given extension type.
551 There are two ways to encode arbitrary extensions.
553 The first way is to use the word ASN1 followed by the extension content
554 using the same syntax as L<ASN1_generate_nconf(3)>.
558 1.2.3.4 = critical, ASN1:UTF8String:Some random data
559 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
565 It is also possible to use the word DER to include the raw encoded data in any
568 1.2.3.4 = critical, DER:01:02:03:04
569 1.2.3.4.1 = DER:01020304
571 The value following DER is a hex dump of the DER encoding of the extension
572 Any extension can be placed in this form to override the default behaviour.
575 basicConstraints = critical, DER:00:01:02:03
579 There is no guarantee that a specific implementation will process a given
580 extension. It may therefore be sometimes possible to use certificates for
581 purposes prohibited by their extensions because a specific application does
582 not recognize or honour the values of the relevant extensions.
584 The DER and ASN1 options should be used with caution. It is possible to create
585 invalid extensions if they are not used carefully.
589 L<openssl-req(1)>, L<openssl-ca(1)>, L<openssl-x509(1)>,
590 L<ASN1_generate_nconf(3)>
594 Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved.
596 Licensed under the Apache License 2.0 (the "License"). You may not use
597 this file except in compliance with the License. You can obtain a copy
598 in the file LICENSE in the source distribution or at
599 L<https://www.openssl.org/source/license.html>.