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 The syntax of this file is described in L<config(5)>.
12 The commands typically have an option to specify the name of the configuration
13 file, and a section within that file; see the documentation of the
14 individual command for details.
16 This page uses B<extensions> as the name of the section, when needed
19 Each entry in the extension section takes the form:
21 name = [critical, ]value(s)
23 If B<critical> is present then the extension will be marked as critical.
25 The format of B<values> depends on the value of B<name>, many have a
26 type-value pairing where the type and value are separated by a colon.
27 There are four main types of extension:
34 Each is described in the following paragraphs.
36 String extensions simply have a string which contains either the value itself
37 or how it is obtained.
39 Multi-valued extensions have a short form and a long form. The short form
40 is a commma-separated list of names and values:
42 basicConstraints = critical, CA:true, pathlen:1
44 The long form allows the values to be placed in a separate section:
47 basicConstraints = critical, @basic_constraints
53 Both forms are equivalent.
55 If an extension is multi-value and a field value must contain a comma the long
56 form must be used otherwise the comma would be misinterpreted as a field
57 separator. For example:
59 subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
61 will produce an error but the equivalent form:
64 subjectAltName = @subject_alt_section
67 subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
71 OpenSSL does not support multiple occurences of the same field within a
72 section. In this example:
75 subjectAltName = @alt_section
81 will only recognize the last value. To specify multiple values append a
82 numeric identifier, as shown here:
85 subjectAltName = @alt_section
91 The syntax of raw extensions is defined by the source code that parses
92 the extension but should be documened.
93 See L</Certificate Policies> for an example of a raw extension.
95 If an extension type is unsupported, then the I<arbitrary> extension syntax
96 must be used, see the L</ARBITRARY EXTENSIONS> section for more details.
98 =head1 STANDARD EXTENSIONS
100 The following sections describe the syntax of each supported extension.
101 They do not define the semantics of the extension.
103 =head2 Basic Constraints
105 This is a multi-valued extension which indicates whether a certificate is
106 a CA certificate. The first value is B<CA> followed by B<TRUE> or
107 B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a
108 non-negative value can be included.
112 basicConstraints = CA:TRUE
114 basicConstraints = CA:FALSE
116 basicConstraints = critical, CA:TRUE, pathlen:1
118 A CA certificate I<must> include the B<basicConstraints> name with the B<CA>
119 parameter set to B<TRUE>. An end-user certificate must either have B<CA:FALSE>
120 or omit the extension entirely.
121 The B<pathlen> parameter specifies the maximum number of CAs that can appear
122 below this one in a chain. A B<pathlen> of zero means the CA cannot sign
123 any sub-CA's, and can only sign end-entity certificates.
127 Key usage is a multi-valued extension consisting of a list of names of
128 the permitted key usages. The defined values are: C<digitalSignature>,
129 C<nonRepudiation>, C<keyEncipherment>, C<dataEncipherment>, C<keyAgreement>,
130 C<keyCertSign>, C<cRLSign>, C<encipherOnly>, and C<decipherOnly>.
134 keyUsage = digitalSignature, nonRepudiation
136 keyUsage = critical, keyCertSign
138 =head2 Extended Key Usage
140 This extension consists of a list of values indicating purposes for which
141 the certificate public key can be used for, Each value can be either a
142 short text name or an OID.
143 The following text names, and their intended meaning, are known:
147 serverAuth SSL/TLS Web Server Authentication
148 clientAuth SSL/TLS Web Client Authentication
149 codeSigning Code signing
150 emailProtection E-mail Protection (S/MIME)
151 timeStamping Trusted Timestamping
152 OCSPSigning OCSP Signing
153 ipsecIKE ipsec Internet Key Exchange
154 msCodeInd Microsoft Individual Code Signing (authenticode)
155 msCodeCom Microsoft Commercial Code Signing (authenticode)
156 msCTLSign Microsoft Trust List Signing
157 msEFS Microsoft Encrypted File System
161 extendedKeyUsage = critical, codeSigning, 1.2.3.4
163 extendedKeyUsage = serverAuth, clientAuth
165 =head2 Subject Key Identifier
167 This is a string extension with one of two legal values. If it is the word
168 B<hash>, then OpenSSL will follow the process in RFC 5280 to calculate the
170 Otherwise, the value should be a hex string to output directly, however this
171 is strongly discouraged.
175 subjectKeyIdentifier = hash
177 =head2 Authority Key Identifier
179 This extension has two options, B<keyid> and B<issuer>. Either or both
180 can have the value B<always>, indicated by putting a colon between
181 the option and its value.
183 If B<keyid> is present, than an attempt is made to copy the subject key
184 identifier from the parent certificate. If the value B<always> is present,
185 then an error can be returned if the option fails. If B<issuer> is present,
186 an attempt is made to copy the issuer and serial number from the parent
187 certificate. This is done if the B<keyid> option fails, or if B<issuer>
188 has B<always> specified.
192 authorityKeyIdentifier = keyid, issuer
194 authorityKeyIdentifier = keyid, issuer:always
196 =head2 Subject Alternative Name
198 This is a multi-valued extension that supports several types of name
199 identifier, including
200 B<email> (an email address),
201 B<URI> (a uniform resource indicator),
202 B<DNS> (a DNS domain name),
203 B<RID> (a registered ID: OBJECT IDENTIFIER),
204 B<IP> (an IP address),
205 B<dirName> (a distinguished name),
207 The syntax of each is described in the following paragraphs.
209 The B<email> option has a special C<copy> value, which will automatically
210 include any email addresses contained in the certificate subject name in
213 The IP address used in the B<IP> option can be in either IPv4 or IPv6 format.
215 The value of B<dirName> is specifies the configuration section containing
216 the distinguished name to use, as a set of name-value pairs.
217 Multi-valued AVAs can be formed by prefacing the name with a B<+> character.
219 The value of B<otherName> can include arbitrary data associated with an OID;
220 the value should be the OID followed by a semicolon and the content in specified
221 using the syntax in L<ASN1_generate_nconf(3)>.
225 subjectAltName = email:copy, email:my@other.address, URI:http://my.url.here/
227 subjectAltName = IP:192.168.7.1
229 subjectAltName = IP:13::17
231 subjectAltName = email:my@other.address, RID:1.2.3.4
233 subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
236 subjectAltName = dirName:dir_sect
244 =head2 Issuer Alternative Name
246 This extension supports most of the options of subject alternative name;
247 it does not support B<email:copy>.
248 It also adds B<issuer:copy> as an allowed value, which copies any subject
249 alternative names from the issuer certificate, if possible.
253 issuerAltName = issuer:copy
255 =head2 Authority Info Access
257 This extension gives details about how to retrieve information that
258 related to the certificate that the CA makes available. The syntax is
259 B<access_id;location>, where B<access_id> is an object identifier
260 (although only a few values are well-known) and B<location> has the same
261 syntax as subject alternative name (except that B<email:copy> is not supported).
265 authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
267 =head2 CRL distribution points
269 This is a multi-valued extension whose values can be either a name-value
270 pair using the same form as subject alternative name or a single value
271 specifying the section name containing all the distribution point values.
273 When a name-value pair is used, a DistributionPoint extension will
274 be set with the given value as the fullName field as the distributionPoint
275 value, and the reasons and cRLIssuer fields will be omitted.
277 When a single option is used, the value specifies the section, and that
278 section can have the following items:
284 The full name of the distribution point, in the same format as the subject
289 The value is taken as a distinguished name fragment that is set as the
290 value of the nameRelativeToCRLIssuer field.
294 The value must in the same format as the subject alternative name.
298 A multi-value field that contains the reasons for revocation. The recognized
299 values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
300 C<superseded>, C<cessationOfOperation>, C<certificateHold>,
301 C<privilegeWithdrawn>, and C<AACompromise>.
305 Only one of B<fullname> or B<relativename> should be specified.
309 crlDistributionPoints = URI:http://myhost.com/myca.crl
311 crlDistributionPoints = URI:http://my.com/my.crl, URI:http://oth.com/my.crl
313 Full distribution point example:
316 crlDistributionPoints = crldp1_section
319 fullname = URI:http://myhost.com/myca.crl
320 CRLissuer = dirName:issuer_sect
321 reasons = keyCompromise, CACompromise
328 =head2 Issuing Distribution Point
330 This extension should only appear in CRLs. It is a multi-valued extension
331 whose syntax is similar to the "section" pointed to by the CRL distribution
332 points extension. The following names have meaning:
338 The full name of the distribution point, in the same format as the subject
343 The value is taken as a distinguished name fragment that is set as the
344 value of the nameRelativeToCRLIssuer field.
346 =item onlysomereasons
348 A multi-value field that contains the reasons for revocation. The recognized
349 values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>,
350 C<superseded>, C<cessationOfOperation>, C<certificateHold>,
351 C<privilegeWithdrawn>, and C<AACompromise>.
353 =item onlyuser, onlyCA, onlyAA, indirectCRL
355 The value for each of these names is a boolean.
362 issuingDistributionPoint = critical, @idp_section
365 fullname = URI:http://myhost.com/myca.crl
367 onlysomereasons = keyCompromise, CACompromise
369 =head2 Certificate Policies
371 This is a I<raw> extension that supports all of the defined fields of the
372 certificate extension.
374 Policies without qualifiers are specified by giving the OID.
375 Multiple policies are comma-separated. For example:
377 certificatePolicies = 1.2.4.5, 1.1.3.4
379 To include policy qualifiers, use the "@section" syntax to point to a
380 section that specifies all the information.
382 The section referred to must include the policy OID using the name
383 B<policyIdentifier>. cPSuri qualifiers can be included using the syntax:
387 where C<nnn> is a number.
389 userNotice qualifiers can be set using the syntax:
391 userNotice.nnn = @notice
393 The value of the userNotice qualifier is specified in the relevant section.
394 This section can include B<explicitText>, B<organization>, and B<noticeNumbers>
395 options. explicitText and organization are text strings, noticeNumbers is a
396 comma separated list of numbers. The organization and noticeNumbers options
397 (if included) must BOTH be present. Some software might require
398 the B<ia5org> option at the top level; this changes the encoding from
399 Displaytext to IA5String.
404 certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect
407 policyIdentifier = 1.3.5.8
408 CPS.1 = "http://my.host.name/"
409 CPS.2 = "http://my.your.name/"
410 userNotice.1 = @notice
413 explicitText = "Explicit Text Here"
414 organization = "Organisation Name"
415 noticeNumbers = 1, 2, 3, 4
417 The character encoding of explicitText can be specified by prefixing the
418 value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example:
421 explicitText = "UTF8:Explicit Text Here"
423 =head2 Policy Constraints
425 This is a multi-valued extension which consisting of the names
426 B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer
427 value. At least one component must be present.
431 policyConstraints = requireExplicitPolicy:3
433 =head2 Inhibit Any Policy
435 This is a string extension whose value must be a non negative integer.
441 =head2 Name Constraints
443 This is a multi-valued extension. The name should
444 begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of
445 the name and the value follows the syntax of subjectAltName except
447 is not supported and the B<IP> form should consist of an IP addresses and
448 subnet mask separated by a B</>.
452 nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
454 nameConstraints = permitted;email:.somedomain.com
456 nameConstraints = excluded;email:.com
460 This is a string extension. It is parsed, but ignored.
466 =head2 TLS Feature (aka Must Staple)
468 This is a multi-valued extension consisting of a list of TLS extension
469 identifiers. Each identifier may be a number (0..65535) or a supported name.
470 When a TLS client sends a listed extension, the TLS server is expected to
471 include that extension in its reply.
473 The supported names are: B<status_request> and B<status_request_v2>.
477 tlsfeature = status_request
479 =head1 DEPRECATED EXTENSIONS
481 The following extensions are non standard, Netscape specific and largely
482 obsolete. Their use in new applications is discouraged.
484 =head2 Netscape String extensions
486 Netscape Comment (B<nsComment>) is a string extension containing a comment
487 which will be displayed when the certificate is viewed in some browsers.
488 Other extensions of this type are: B<nsBaseUrl>,
489 B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl>
490 and B<nsSslServerName>.
492 =head2 Netscape Certificate Type
494 This is a multi-valued extensions which consists of a list of flags to be
495 included. It was used to indicate the purposes for which a certificate could
496 be used. The basicConstraints, keyUsage and extended key usage extensions are
499 Acceptable values for nsCertType are: B<client>, B<server>, B<email>,
500 B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>.
502 =head1 ARBITRARY EXTENSIONS
504 If an extension is not supported by the OpenSSL code then it must be encoded
505 using the arbitrary extension format. It is also possible to use the arbitrary
506 format for supported extensions. Extreme care should be taken to ensure that
507 the data is formatted correctly for the given extension type.
509 There are two ways to encode arbitrary extensions.
511 The first way is to use the word ASN1 followed by the extension content
512 using the same syntax as L<ASN1_generate_nconf(3)>.
516 1.2.3.4 = critical, ASN1:UTF8String:Some random data
517 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
523 It is also possible to use the word DER to include the raw encoded data in any
526 1.2.3.4 = critical, DER:01:02:03:04
527 1.2.3.4.1 = DER:01020304
529 The value following DER is a hex dump of the DER encoding of the extension
530 Any extension can be placed in this form to override the default behaviour.
533 basicConstraints = critical, DER:00:01:02:03
537 There is no guarantee that a specific implementation will process a given
538 extension. It may therefore be sometimes possible to use certificates for
539 purposes prohibited by their extensions because a specific application does
540 not recognize or honour the values of the relevant extensions.
542 The DER and ASN1 options should be used with caution. It is possible to create
543 invalid extensions if they are not used carefully.
547 L<openssl-req(1)>, L<openssl-ca(1)>, L<openssl-x509(1)>,
548 L<ASN1_generate_nconf(3)>
552 Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.
554 Licensed under the Apache License 2.0 (the "License"). You may not use
555 this file except in compliance with the License. You can obtain a copy
556 in the file LICENSE in the source distribution or at
557 L<https://www.openssl.org/source/license.html>.