1X509V3_CONFIG(5) OpenSSL X509V3_CONFIG(5)
2
6 x509v3_config - X509 V3 certificate extension configuration format
7
9 Several of the OpenSSL utilities can add extensions to a certificate or
10 certificate request based on the contents of a configuration file.
11 Typically the application will contain an option to point to an
13 extension section. Each line of the extension section takes the form:
14 extension_name=[critical,] extension_options
16 If critical is present then the extension will be critical.
18 The format of extension_options depends on the value of extension_name.
20 There are four main types of extension: string extensions, multi-valued
22 extensions, raw and arbitrary extensions.
23 String extensions simply have a string which contains either the value
25 itself or how it is obtained.
26 For example:
28 nsComment="This is a Comment"
30 Multi-valued extensions have a short form and a long form. The short
32 form is a list of names and values:
33 basicConstraints=critical,CA:true,pathlen:1
35 The long form allows the values to be placed in a separate section:
37 basicConstraints=critical,@bs_section
39 [bs_section]
41 CA=true
43 pathlen=1
44 Both forms are equivalent.
46 The syntax of raw extensions is governed by the extension code: it can
48 for example contain data in multiple sections. The correct syntax to
49 use is defined by the extension code itself: check out the certificate
50 policies extension for an example.
51 If an extension type is unsupported then the arbitrary extension syntax
53 must be used, see the ARBITRARY EXTENSIONS section for more details.
54
56 The following sections describe each supported extension in detail.
57 Basic Constraints.
59 This is a multi valued extension which indicates whether a certificate
60 is a CA certificate. The first (mandatory) name is CA followed by TRUE
61 or FALSE. If CA is TRUE then an optional pathlen name followed by a
62 nonnegative value can be included.
63 For example:
65 basicConstraints=CA:TRUE
67 basicConstraints=CA:FALSE
69 basicConstraints=critical,CA:TRUE, pathlen:0
71 A CA certificate must include the basicConstraints value with the CA
73 field set to TRUE. An end user certificate must either set CA to FALSE
74 or exclude the extension entirely. Some software may require the
75 inclusion of basicConstraints with CA set to FALSE for end entity
76 certificates.
77 The pathlen parameter indicates the maximum number of CAs that can
79 appear below this one in a chain. So if you have a CA with a pathlen of
80 zero it can only be used to sign end user certificates and not further
81 CAs.
82 Key Usage.
84 Key usage is a multi valued extension consisting of a list of names of
85 the permitted key usages.
86 The supported names are: digitalSignature, nonRepudiation,
88 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
89 encipherOnly and decipherOnly.
90 Examples:
92 keyUsage=digitalSignature, nonRepudiation
94 keyUsage=critical, keyCertSign
96 Extended Key Usage.
98 This extensions consists of a list of usages indicating purposes for
99 which the certificate public key can be used for,
100 These can either be object short names or the dotted numerical form of
102 OIDs. While any OID can be used only certain values make sense. In
103 particular the following PKIX, NS and MS values are meaningful:
104 Value Meaning
106 ----- -------
107 serverAuth SSL/TLS Web Server Authentication.
108 clientAuth SSL/TLS Web Client Authentication.
109 codeSigning Code signing.
110 emailProtection E-mail Protection (S/MIME).
111 timeStamping Trusted Timestamping
112 OCSPSigning OCSP Signing
113 ipsecIKE ipsec Internet Key Exchange
114 msCodeInd Microsoft Individual Code Signing (authenticode)
115 msCodeCom Microsoft Commercial Code Signing (authenticode)
116 msCTLSign Microsoft Trust List Signing
117 msEFS Microsoft Encrypted File System
118 Examples:
120 extendedKeyUsage=critical,codeSigning,1.2.3.4
122 extendedKeyUsage=serverAuth,clientAuth
123 Subject Key Identifier.
125 This is really a string extension and can take two possible values.
126 Either the word hash which will automatically follow the guidelines in
127 RFC3280 or a hex string giving the extension value to include. The use
128 of the hex string is strongly discouraged.
129 Example:
131 subjectKeyIdentifier=hash
133 Authority Key Identifier.
135 The authority key identifier extension permits two options. keyid and
136 issuer: both can take the optional value "always".
137 If the keyid option is present an attempt is made to copy the subject
139 key identifier from the parent certificate. If the value "always" is
140 present then an error is returned if the option fails.
141 The issuer option copies the issuer and serial number from the issuer
143 certificate. This will only be done if the keyid option fails or is not
144 included unless the "always" flag will always include the value.
145 Example:
147 authorityKeyIdentifier=keyid,issuer
149 Subject Alternative Name.
151 The subject alternative name extension allows various literal values to
152 be included in the configuration file. These include email (an email
153 address) URI a uniform resource indicator, DNS (a DNS domain name), RID
154 (a registered ID: OBJECT IDENTIFIER), IP (an IP address), dirName (a
155 distinguished name) and otherName.
156 The email option include a special 'copy' value. This will
158 automatically include any email addresses contained in the certificate
159 subject name in the extension.
160 The IP address used in the IP options can be in either IPv4 or IPv6
162 format.
163 The value of dirName should point to a section containing the
165 distinguished name to use as a set of name value pairs. Multi values
166 AVAs can be formed by prefacing the name with a + character.
167 otherName can include arbitrary data associated with an OID: the value
169 should be the OID followed by a semicolon and the content in standard
170 ASN1_generate_nconf(3) format.
171 Examples:
173 subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
175 subjectAltName=IP:192.168.7.1
176 subjectAltName=IP:13::17
177 subjectAltName=email:my@other.address,RID:1.2.3.4
178 subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
179 subjectAltName=dirName:dir_sect
181 [dir_sect]
183 C=UK
184 O=My Organization
185 OU=My Unit
186 CN=My Name
187 Issuer Alternative Name.
189 The issuer alternative name option supports all the literal options of
190 subject alternative name. It does not support the email:copy option
191 because that would not make sense. It does support an additional
192 issuer:copy option that will copy all the subject alternative name
193 values from the issuer certificate (if possible).
194 Example:
196 issuerAltName = issuer:copy
198 Authority Info Access.
200 The authority information access extension gives details about how to
201 access certain information relating to the CA. Its syntax is
202 accessOID;location where location has the same syntax as subject
203 alternative name (except that email:copy is not supported). accessOID
204 can be any valid OID but only certain values are meaningful, for
205 example OCSP and caIssuers.
206 Example:
208 authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
210 authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
211 CRL distribution points
213 This is a multi-valued extension whose options can be either in
214 name:value pair using the same form as subject alternative name or a
215 single value representing a section name containing all the
216 distribution point fields.
217 For a name:value pair a new DistributionPoint with the fullName field
219 set to the given value both the cRLissuer and reasons fields are
220 omitted in this case.
221 In the single option case the section indicated contains values for
223 each field. In this section:
224 If the name is "fullname" the value field should contain the full name
226 of the distribution point in the same format as subject alternative
227 name.
228 If the name is "relativename" then the value field should contain a
230 section name whose contents represent a DN fragment to be placed in
231 this field.
232 The name "CRLIssuer" if present should contain a value for this field
234 in subject alternative name format.
235 If the name is "reasons" the value field should consist of a comma
237 separated field containing the reasons. Valid reasons are:
238 "keyCompromise", "CACompromise", "affiliationChanged", "superseded",
239 "cessationOfOperation", "certificateHold", "privilegeWithdrawn" and
240 "AACompromise".
241 Simple examples:
243 crlDistributionPoints=URI:http://myhost.com/myca.crl
245 crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
246 Full distribution point example:
248 crlDistributionPoints=crldp1_section
250 [crldp1_section]
252 fullname=URI:http://myhost.com/myca.crl
254 CRLissuer=dirName:issuer_sect
255 reasons=keyCompromise, CACompromise
256 [issuer_sect]
258 C=UK
259 O=Organisation
260 CN=Some Name
261 Issuing Distribution Point
263 This extension should only appear in CRLs. It is a multi valued
264 extension whose syntax is similar to the "section" pointed to by the
265 CRL distribution points extension with a few differences.
266 The names "reasons" and "CRLissuer" are not recognized.
268 The name "onlysomereasons" is accepted which sets this field. The value
270 is in the same format as the CRL distribution point "reasons" field.
271 The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also
273 accepted the values should be a boolean value (TRUE or FALSE) to
274 indicate the value of the corresponding field.
275 Example:
277 issuingDistributionPoint=critical, @idp_section
279 [idp_section]
281 fullname=URI:http://myhost.com/myca.crl
283 indirectCRL=TRUE
284 onlysomereasons=keyCompromise, CACompromise
285 [issuer_sect]
287 C=UK
288 O=Organisation
289 CN=Some Name
290 Certificate Policies.
292 This is a raw extension. All the fields of this extension can be set by
293 using the appropriate syntax.
294 If you follow the PKIX recommendations and just using one OID then you
296 just include the value of that OID. Multiple OIDs can be set separated
297 by commas, for example:
298 certificatePolicies= 1.2.4.5, 1.1.3.4
300 If you wish to include qualifiers then the policy OID and qualifiers
302 need to be specified in a separate section: this is done by using the
303 @section syntax instead of a literal OID value.
304 The section referred to must include the policy OID using the name
306 policyIdentifier, cPSuri qualifiers can be included using the syntax:
307 CPS.nnn=value
309 userNotice qualifiers can be set using the syntax:
311 userNotice.nnn=@notice
313 The value of the userNotice qualifier is specified in the relevant
315 section. This section can include explicitText, organization and
316 noticeNumbers options. explicitText and organization are text strings,
317 noticeNumbers is a comma separated list of numbers. The organization
318 and noticeNumbers options (if included) must BOTH be present. If you
319 use the userNotice option with IE5 then you need the 'ia5org' option at
320 the top level to modify the encoding: otherwise it will not be
321 interpreted properly.
322 Example:
324 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
326 [polsect]
328 policyIdentifier = 1.3.5.8
330 CPS.1="http://my.host.name/"
331 CPS.2="http://my.your.name/"
332 userNotice.1=@notice
333 [notice]
335 explicitText="Explicit Text Here"
337 organization="Organisation Name"
338 noticeNumbers=1,2,3,4
339 The ia5org option changes the type of the organization field. In
341 RFC2459 it can only be of type DisplayText. In RFC3280 IA5String is
342 also permissible. Some software (for example some versions of MSIE)
343 may require ia5org.
344 ASN1 type of explicitText can be specified by prepending UTF8, BMP or
346 VISIBLE prefix followed by colon. For example:
347 [notice]
349 explicitText="UTF8:Explicit Text Here"
350 Policy Constraints
352 This is a multi-valued extension which consisting of the names
353 requireExplicitPolicy or inhibitPolicyMapping and a non negative
354 integer value. At least one component must be present.
355 Example:
357 policyConstraints = requireExplicitPolicy:3
359 Inhibit Any Policy
361 This is a string extension whose value must be a non negative integer.
362 Example:
364 inhibitAnyPolicy = 2
366 Name Constraints
368 The name constraints extension is a multi-valued extension. The name
369 should begin with the word permitted or excluded followed by a ;. The
370 rest of the name and the value follows the syntax of subjectAltName
371 except email:copy is not supported and the IP form should consist of an
372 IP addresses and subnet mask separated by a /.
373 Examples:
375 nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
377 nameConstraints=permitted;email:.somedomain.com
379 nameConstraints=excluded;email:.com
381 OCSP No Check
383 The OCSP No Check extension is a string extension but its value is
384 ignored.
385 Example:
387 noCheck = ignored
389 TLS Feature (aka Must Staple)
391 This is a multi-valued extension consisting of a list of TLS extension
392 identifiers. Each identifier may be a number (0..65535) or a supported
393 name. When a TLS client sends a listed extension, the TLS server is
394 expected to include that extension in its reply.
395 The supported names are: status_request and status_request_v2.
397 Example:
399 tlsfeature = status_request
401
403 The following extensions are non standard, Netscape specific and
404 largely obsolete. Their use in new applications is discouraged.
405 Netscape String extensions.
407 Netscape Comment (nsComment) is a string extension containing a comment
408 which will be displayed when the certificate is viewed in some
409 browsers.
410 Example:
412 nsComment = "Some Random Comment"
414 Other supported extensions in this category are: nsBaseUrl,
416 nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and
417 nsSslServerName.
418 Netscape Certificate Type
420 This is a multi-valued extensions which consists of a list of flags to
421 be included. It was used to indicate the purposes for which a
422 certificate could be used. The basicConstraints, keyUsage and extended
423 key usage extensions are now used instead.
424 Acceptable values for nsCertType are: client, server, email, objsign,
426 reserved, sslCA, emailCA, objCA.
427
429 If an extension is not supported by the OpenSSL code then it must be
430 encoded using the arbitrary extension format. It is also possible to
431 use the arbitrary format for supported extensions. Extreme care should
432 be taken to ensure that the data is formatted correctly for the given
433 extension type.
434 There are two ways to encode arbitrary extensions.
436 The first way is to use the word ASN1 followed by the extension content
438 using the same syntax as ASN1_generate_nconf(3). For example:
439 1.2.3.4=critical,ASN1:UTF8String:Some random data
441 1.2.3.4=ASN1:SEQUENCE:seq_sect
443 [seq_sect]
445 field1 = UTF8:field1
447 field2 = UTF8:field2
448 It is also possible to use the word DER to include the raw encoded data
450 in any extension.
451 1.2.3.4=critical,DER:01:02:03:04
453 1.2.3.4=DER:01020304
454 The value following DER is a hex dump of the DER encoding of the
456 extension Any extension can be placed in this form to override the
457 default behaviour. For example:
458 basicConstraints=critical,DER:00:01:02:03
460
462 There is no guarantee that a specific implementation will process a
463 given extension. It may therefore be sometimes possible to use
464 certificates for purposes prohibited by their extensions because a
465 specific application does not recognize or honour the values of the
466 relevant extensions.
467 The DER and ASN1 options should be used with caution. It is possible to
469 create totally invalid extensions if they are not used carefully.
470
472 If an extension is multi-value and a field value must contain a comma
473 the long form must be used otherwise the comma would be misinterpreted
474 as a field separator. For example:
475 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
477 will produce an error but the equivalent form:
479 subjectAltName=@subject_alt_section
481 [subject_alt_section]
483 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
484 is valid.
486 Due to the behaviour of the OpenSSL conf library the same field name
488 can only occur once in a section. This means that:
489 subjectAltName=@alt_section
491 [alt_section]
493 email=steve@here
495 email=steve@there
496 will only recognize the last value. This can be worked around by using
498 the form:
499 [alt_section]
501 email.1=steve@here
503 email.2=steve@there
504
506 req(1), ca(1), x509(1), ASN1_generate_nconf(3)
507
509 Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved.
510 Licensed under the OpenSSL license (the "License"). You may not use
512 this file except in compliance with the License. You can obtain a copy
513 in the file LICENSE in the source distribution or at
514 <https://www.openssl.org/source/license.html>.
5151.1.1l 2021-09-15 X509V3_CONFIG(5)