1X509V3_CONFIG(5ossl) OpenSSL X509V3_CONFIG(5ossl)
2
6 x509v3_config - X509 V3 certificate extension configuration format
7
9 Several OpenSSL commands can add extensions to a certificate or
10 certificate request based on the contents of a configuration file and
11 CLI options such as -addext. The syntax of configuration files is
12 described in config(5). The commands typically have an option to
13 specify the name of the configuration file, and a section within that
14 file; see the documentation of the individual command for details.
15 This page uses extensions as the name of the section, when needed in
17 examples.
18 Each entry in the extension section takes the form:
20 name = [critical, ]value(s)
22 If critical is present then the extension will be marked as critical.
24 If multiple entries are processed for the same extension name, later
26 entries override earlier ones with the same name.
27 The format of values depends on the value of name, many have a type-
29 value pairing where the type and value are separated by a colon. There
30 are four main types of extension:
31 string
33 multi-valued
34 raw
35 arbitrary
36 Each is described in the following paragraphs.
38 String extensions simply have a string which contains either the value
40 itself or how it is obtained.
41 Multi-valued extensions have a short form and a long form. The short
43 form is a comma-separated list of names and values:
44 basicConstraints = critical, CA:true, pathlen:1
46 The long form allows the values to be placed in a separate section:
48 [extensions]
50 basicConstraints = critical, @basic_constraints
51 [basic_constraints]
53 CA = true
54 pathlen = 1
55 Both forms are equivalent.
57 If an extension is multi-value and a field value must contain a comma
59 the long form must be used otherwise the comma would be misinterpreted
60 as a field separator. For example:
61 subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
63 will produce an error but the equivalent form:
65 [extensions]
67 subjectAltName = @subject_alt_section
68 [subject_alt_section]
70 subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
71 is valid.
73 OpenSSL does not support multiple occurrences of the same field within
75 a section. In this example:
76 [extensions]
78 subjectAltName = @alt_section
79 [alt_section]
81 email = steve@example.com
82 email = steve@example.org
83 will only recognize the last value. To specify multiple values append
85 a numeric identifier, as shown here:
86 [extensions]
88 subjectAltName = @alt_section
89 [alt_section]
91 email.1 = steve@example.com
92 email.2 = steve@example.org
93 The syntax of raw extensions is defined by the source code that parses
95 the extension but should be documened. See "Certificate Policies" for
96 an example of a raw extension.
97 If an extension type is unsupported, then the arbitrary extension
99 syntax must be used, see the "ARBITRARY EXTENSIONS" section for more
100 details.
101
103 The following sections describe the syntax of each supported extension.
104 They do not define the semantics of the extension.
105 Basic Constraints
107 This is a multi-valued extension which indicates whether a certificate
108 is a CA certificate. The first value is CA followed by TRUE or FALSE.
109 If CA is TRUE then an optional pathlen name followed by a nonnegative
110 value can be included.
111 For example:
113 basicConstraints = CA:TRUE
115 basicConstraints = CA:FALSE
117 basicConstraints = critical, CA:TRUE, pathlen:1
119 A CA certificate must include the basicConstraints name with the CA
121 parameter set to TRUE. An end-user certificate must either have
122 CA:FALSE or omit the extension entirely. The pathlen parameter
123 specifies the maximum number of CAs that can appear below this one in a
124 chain. A pathlen of zero means the CA cannot sign any sub-CA's, and can
125 only sign end-entity certificates.
126 Key Usage
128 Key usage is a multi-valued extension consisting of a list of names of
129 the permitted key usages. The defined values are: "digitalSignature",
130 "nonRepudiation", "keyEncipherment", "dataEncipherment",
131 "keyAgreement", "keyCertSign", "cRLSign", "encipherOnly", and
132 "decipherOnly".
133 Examples:
135 keyUsage = digitalSignature, nonRepudiation
137 keyUsage = critical, keyCertSign
139 Extended Key Usage
141 This extension consists of a list of values indicating purposes for
142 which the certificate public key can be used. Each value can be either
143 a short text name or an OID. The following text names, and their
144 intended meaning, are known:
145 Value Meaning according to RFC 5280 etc.
147 ----- ----------------------------------
148 serverAuth SSL/TLS WWW Server Authentication
149 clientAuth SSL/TLS WWW Client Authentication
150 codeSigning Code Signing
151 emailProtection E-mail Protection (S/MIME)
152 timeStamping Trusted Timestamping
153 OCSPSigning OCSP Signing
154 ipsecIKE ipsec Internet Key Exchange
155 msCodeInd Microsoft Individual Code Signing (authenticode)
156 msCodeCom Microsoft Commercial Code Signing (authenticode)
157 msCTLSign Microsoft Trust List Signing
158 msEFS Microsoft Encrypted File System
159 While IETF RFC 5280 says that id-kp-serverAuth and id-kp-clientAuth are
161 only for WWW use, in practice they are used for all kinds of TLS
162 clients and servers, and this is what OpenSSL assumes as well.
163 Examples:
165 extendedKeyUsage = critical, codeSigning, 1.2.3.4
167 extendedKeyUsage = serverAuth, clientAuth
169 Subject Key Identifier
171 The SKID extension specification has a value with three choices. If
172 the value is the word none then no SKID extension will be included. If
173 the value is the word hash, or by default for the x509, req, and ca
174 apps, the process specified in RFC 5280 section 4.2.1.2. (1) is
175 followed: The keyIdentifier is composed of the 160-bit SHA-1 hash of
176 the value of the BIT STRING subjectPublicKey (excluding the tag,
177 length, and number of unused bits).
178 Otherwise, the value must be a hex string (possibly with ":" separating
180 bytes) to output directly, however, this is strongly discouraged.
181 Example:
183 subjectKeyIdentifier = hash
185 Authority Key Identifier
187 The AKID extension specification may have the value none indicating
188 that no AKID shall be included. Otherwise it may have the value keyid
189 or issuer or both of them, separated by ",". Either or both can have
190 the option always, indicated by putting a colon ":" between the value
191 and this option. For self-signed certificates the AKID is suppressed
192 unless always is present. By default the x509, req, and ca apps behave
193 as if "none" was given for self-signed certificates and "keyid, issuer"
194 otherwise.
195 If keyid is present, an attempt is made to copy the subject key
197 identifier (SKID) from the issuer certificate except if the issuer
198 certificate is the same as the current one and it is not self-signed.
199 The hash of the public key related to the signing key is taken as
200 fallback if the issuer certificate is the same as the current
201 certificate. If always is present but no value can be obtained, an
202 error is returned.
203 If issuer is present, and in addition it has the option always
205 specified or keyid is not present, then the issuer DN and serial number
206 are copied from the issuer certificate.
207 Examples:
209 authorityKeyIdentifier = keyid, issuer
211 authorityKeyIdentifier = keyid, issuer:always
213 Subject Alternative Name
215 This is a multi-valued extension that supports several types of name
216 identifier, including email (an email address), URI (a uniform resource
217 indicator), DNS (a DNS domain name), RID (a registered ID: OBJECT
218 IDENTIFIER), IP (an IP address), dirName (a distinguished name), and
219 otherName. The syntax of each is described in the following
220 paragraphs.
221 The email option has two special values. "copy" will automatically
223 include any email addresses contained in the certificate subject name
224 in the extension. "move" will automatically move any email addresses
225 from the certificate subject name to the extension.
226 The IP address used in the IP option can be in either IPv4 or IPv6
228 format.
229 The value of dirName is specifies the configuration section containing
231 the distinguished name to use, as a set of name-value pairs. Multi-
232 valued AVAs can be formed by prefacing the name with a + character.
233 The value of otherName can include arbitrary data associated with an
235 OID; the value should be the OID followed by a semicolon and the
236 content in specified using the syntax in ASN1_generate_nconf(3).
237 Examples:
239 subjectAltName = email:copy, email:my@example.com, URI:http://my.example.com/
241 subjectAltName = IP:192.168.7.1
243 subjectAltName = IP:13::17
245 subjectAltName = email:my@example.com, RID:1.2.3.4
247 subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
249 [extensions]
251 subjectAltName = dirName:dir_sect
252 [dir_sect]
254 C = UK
255 O = My Organization
256 OU = My Unit
257 CN = My Name
258 Non-ASCII Email Address conforming the syntax defined in Section 3.3 of
260 RFC 6531 are provided as otherName.SmtpUTF8Mailbox. According to RFC
261 8398, the email address should be provided as UTF8String. To enforce
262 the valid representation in the certificate, the SmtpUTF8Mailbox should
263 be provided as follows
264 subjectAltName=@alts
266 [alts]
267 otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com
268 Issuer Alternative Name
270 This extension supports most of the options of subject alternative
271 name; it does not support email:copy. It also adds issuer:copy as an
272 allowed value, which copies any subject alternative names from the
273 issuer certificate, if possible.
274 Example:
276 issuerAltName = issuer:copy
278 Authority Info Access
280 This extension gives details about how to retrieve information that
281 related to the certificate that the CA makes available. The syntax is
282 access_id;location, where access_id is an object identifier (although
283 only a few values are well-known) and location has the same syntax as
284 subject alternative name (except that email:copy is not supported).
285 Possible values for access_id include OCSP (OCSP responder), caIssuers
287 (CA Issuers), ad_timestamping (AD Time Stamping), AD_DVCS (ad dvcs),
288 caRepository (CA Repository).
289 Examples:
291 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer
293 authorityInfoAccess = OCSP;URI:http://ocsp.example.com/
295 CRL distribution points
297 This is a multi-valued extension whose values can be either a name-
298 value pair using the same form as subject alternative name or a single
299 value specifying the section name containing all the distribution point
300 values.
301 When a name-value pair is used, a DistributionPoint extension will be
303 set with the given value as the fullName field as the distributionPoint
304 value, and the reasons and cRLIssuer fields will be omitted.
305 When a single option is used, the value specifies the section, and that
307 section can have the following items:
308 fullname
310 The full name of the distribution point, in the same format as the
311 subject alternative name.
312 relativename
314 The value is taken as a distinguished name fragment that is set as
315 the value of the nameRelativeToCRLIssuer field.
316 CRLIssuer
318 The value must in the same format as the subject alternative name.
319 reasons
321 A multi-value field that contains the reasons for revocation. The
322 recognized values are: "keyCompromise", "CACompromise",
323 "affiliationChanged", "superseded", "cessationOfOperation",
324 "certificateHold", "privilegeWithdrawn", and "AACompromise".
325 Only one of fullname or relativename should be specified.
327 Simple examples:
329 crlDistributionPoints = URI:http://example.com/myca.crl
331 crlDistributionPoints = URI:http://example.com/myca.crl, URI:http://example.org/my.crl
333 Full distribution point example:
335 [extensions]
337 crlDistributionPoints = crldp1_section
338 [crldp1_section]
340 fullname = URI:http://example.com/myca.crl
341 CRLissuer = dirName:issuer_sect
342 reasons = keyCompromise, CACompromise
343 [issuer_sect]
345 C = UK
346 O = Organisation
347 CN = Some Name
348 Issuing Distribution Point
350 This extension should only appear in CRLs. It is a multi-valued
351 extension whose syntax is similar to the "section" pointed to by the
352 CRL distribution points extension. The following names have meaning:
353 fullname
355 The full name of the distribution point, in the same format as the
356 subject alternative name.
357 relativename
359 The value is taken as a distinguished name fragment that is set as
360 the value of the nameRelativeToCRLIssuer field.
361 onlysomereasons
363 A multi-value field that contains the reasons for revocation. The
364 recognized values are: "keyCompromise", "CACompromise",
365 "affiliationChanged", "superseded", "cessationOfOperation",
366 "certificateHold", "privilegeWithdrawn", and "AACompromise".
367 onlyuser, onlyCA, onlyAA, indirectCRL
369 The value for each of these names is a boolean.
370 Example:
372 [extensions]
374 issuingDistributionPoint = critical, @idp_section
375 [idp_section]
377 fullname = URI:http://example.com/myca.crl
378 indirectCRL = TRUE
379 onlysomereasons = keyCompromise, CACompromise
380 Certificate Policies
382 This is a raw extension that supports all of the defined fields of the
383 certificate extension.
384 Policies without qualifiers are specified by giving the OID. Multiple
386 policies are comma-separated. For example:
387 certificatePolicies = 1.2.4.5, 1.1.3.4
389 To include policy qualifiers, use the "@section" syntax to point to a
391 section that specifies all the information.
392 The section referred to must include the policy OID using the name
394 policyIdentifier. cPSuri qualifiers can be included using the syntax:
395 CPS.nnn = value
397 where "nnn" is a number.
399 userNotice qualifiers can be set using the syntax:
401 userNotice.nnn = @notice
403 The value of the userNotice qualifier is specified in the relevant
405 section. This section can include explicitText, organization, and
406 noticeNumbers options. explicitText and organization are text strings,
407 noticeNumbers is a comma separated list of numbers. The organization
408 and noticeNumbers options (if included) must BOTH be present. Some
409 software might require the ia5org option at the top level; this changes
410 the encoding from Displaytext to IA5String.
411 Example:
413 [extensions]
415 certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect
416 [polsect]
418 policyIdentifier = 1.3.5.8
419 CPS.1 = "http://my.host.example.com/"
420 CPS.2 = "http://my.your.example.com/"
421 userNotice.1 = @notice
422 [notice]
424 explicitText = "Explicit Text Here"
425 organization = "Organisation Name"
426 noticeNumbers = 1, 2, 3, 4
427 The character encoding of explicitText can be specified by prefixing
429 the value with UTF8, BMP, or VISIBLE followed by colon. For example:
430 [notice]
432 explicitText = "UTF8:Explicit Text Here"
433 Policy Constraints
435 This is a multi-valued extension which consisting of the names
436 requireExplicitPolicy or inhibitPolicyMapping and a non negative
437 integer value. At least one component must be present.
438 Example:
440 policyConstraints = requireExplicitPolicy:3
442 Inhibit Any Policy
444 This is a string extension whose value must be a non negative integer.
445 Example:
447 inhibitAnyPolicy = 2
449 Name Constraints
451 This is a multi-valued extension. The name should begin with the word
452 permitted or excluded followed by a ;. The rest of the name and the
453 value follows the syntax of subjectAltName except email:copy is not
454 supported and the IP form should consist of an IP addresses and subnet
455 mask separated by a /.
456 Examples:
458 nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
460 nameConstraints = permitted;email:.example.com
462 nameConstraints = excluded;email:.com
464 OCSP No Check
466 This is a string extension. It is parsed, but ignored.
467 Example:
469 noCheck = ignored
471 TLS Feature (aka Must Staple)
473 This is a multi-valued extension consisting of a list of TLS extension
474 identifiers. Each identifier may be a number (0..65535) or a supported
475 name. When a TLS client sends a listed extension, the TLS server is
476 expected to include that extension in its reply.
477 The supported names are: status_request and status_request_v2.
479 Example:
481 tlsfeature = status_request
483
485 The following extensions are non standard, Netscape specific and
486 largely obsolete. Their use in new applications is discouraged.
487 Netscape String extensions
489 Netscape Comment (nsComment) is a string extension containing a comment
490 which will be displayed when the certificate is viewed in some
491 browsers. Other extensions of this type are: nsBaseUrl,
492 nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and
493 nsSslServerName.
494 Netscape Certificate Type
496 This is a multi-valued extensions which consists of a list of flags to
497 be included. It was used to indicate the purposes for which a
498 certificate could be used. The basicConstraints, keyUsage and extended
499 key usage extensions are now used instead.
500 Acceptable values for nsCertType are: client, server, email, objsign,
502 reserved, sslCA, emailCA, objCA.
503
505 If an extension is not supported by the OpenSSL code then it must be
506 encoded using the arbitrary extension format. It is also possible to
507 use the arbitrary format for supported extensions. Extreme care should
508 be taken to ensure that the data is formatted correctly for the given
509 extension type.
510 There are two ways to encode arbitrary extensions.
512 The first way is to use the word ASN1 followed by the extension content
514 using the same syntax as ASN1_generate_nconf(3). For example:
515 [extensions]
517 1.2.3.4 = critical, ASN1:UTF8String:Some random data
518 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
519 [seq_sect]
521 field1 = UTF8:field1
522 field2 = UTF8:field2
523 It is also possible to use the word DER to include the raw encoded data
525 in any extension.
526 1.2.3.4 = critical, DER:01:02:03:04
528 1.2.3.4.1 = DER:01020304
529 The value following DER is a hex dump of the DER encoding of the
531 extension Any extension can be placed in this form to override the
532 default behaviour. For example:
533 basicConstraints = critical, DER:00:01:02:03
535
537 There is no guarantee that a specific implementation will process a
538 given extension. It may therefore be sometimes possible to use
539 certificates for purposes prohibited by their extensions because a
540 specific application does not recognize or honour the values of the
541 relevant extensions.
542 The DER and ASN1 options should be used with caution. It is possible to
544 create invalid extensions if they are not used carefully.
545
547 openssl-req(1), openssl-ca(1), openssl-x509(1), ASN1_generate_nconf(3)
548
550 Copyright 2004-2021 The OpenSSL Project Authors. All Rights Reserved.
551 Licensed under the Apache License 2.0 (the "License"). You may not use
553 this file except in compliance with the License. You can obtain a copy
554 in the file LICENSE in the source distribution or at
555 <https://www.openssl.org/source/license.html>.
5563.0.5 2022-07-05 X509V3_CONFIG(5ossl)