1X509V3_CONFIG(5)                    OpenSSL                   X509V3_CONFIG(5)
2
3
4

NAME

6       x509v3_config - X509 V3 certificate extension configuration format
7

DESCRIPTION

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
12       Typically the application will contain an option to point to an
13       extension section. Each line of the extension section takes the form:
14
15        extension_name=[critical,] extension_options
16
17       If critical is present then the extension will be critical.
18
19       The format of extension_options depends on the value of extension_name.
20
21       There are four main types of extension: string extensions, multi-valued
22       extensions, raw and arbitrary extensions.
23
24       String extensions simply have a string which contains either the value
25       itself or how it is obtained.
26
27       For example:
28
29        nsComment="This is a Comment"
30
31       Multi-valued extensions have a short form and a long form. The short
32       form is a list of names and values:
33
34        basicConstraints=critical,CA:true,pathlen:1
35
36       The long form allows the values to be placed in a separate section:
37
38        basicConstraints=critical,@bs_section
39
40        [bs_section]
41
42        CA=true
43        pathlen=1
44
45       Both forms are equivalent.
46
47       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
52       If an extension type is unsupported then the arbitrary extension syntax
53       must be used, see the ARBITRARY EXTENSIONS section for more details.
54

STANDARD EXTENSIONS

56       The following sections describe each supported extension in detail.
57
58   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 an
62       non-negative value can be included.
63
64       For example:
65
66        basicConstraints=CA:TRUE
67
68        basicConstraints=CA:FALSE
69
70        basicConstraints=critical,CA:TRUE, pathlen:0
71
72       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
78       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
83   Key Usage.
84       Key usage is a multi valued extension consisting of a list of names of
85       the permitted key usages.
86
87       The supported names are: digitalSignature, nonRepudiation,
88       keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
89       encipherOnly and decipherOnly.
90
91       Examples:
92
93        keyUsage=digitalSignature, nonRepudiation
94
95        keyUsage=critical, keyCertSign
96
97   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
101       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
105        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
119       Examples:
120
121        extendedKeyUsage=critical,codeSigning,1.2.3.4
122        extendedKeyUsage=serverAuth,clientAuth
123
124   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
130       Example:
131
132        subjectKeyIdentifier=hash
133
134   Authority Key Identifier.
135       The authority key identifier extension permits two options. keyid and
136       issuer: both can take the optional value "always".
137
138       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
142       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
146       Example:
147
148        authorityKeyIdentifier=keyid,issuer
149
150   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
157       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
161       The IP address used in the IP options can be in either IPv4 or IPv6
162       format.
163
164       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
168       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
172       Examples:
173
174        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
180        subjectAltName=dirName:dir_sect
181
182        [dir_sect]
183        C=UK
184        O=My Organization
185        OU=My Unit
186        CN=My Name
187
188   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
195       Example:
196
197        issuerAltName = issuer:copy
198
199   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
207       Example:
208
209        authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
210        authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
211
212   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
218       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
222       In the single option case the section indicated contains values for
223       each field. In this section:
224
225       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
229       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
233       The name "CRLIssuer" if present should contain a value for this field
234       in subject alternative name format.
235
236       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
242       Simple examples:
243
244        crlDistributionPoints=URI:http://myhost.com/myca.crl
245        crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
246
247       Full distribution point example:
248
249        crlDistributionPoints=crldp1_section
250
251        [crldp1_section]
252
253        fullname=URI:http://myhost.com/myca.crl
254        CRLissuer=dirName:issuer_sect
255        reasons=keyCompromise, CACompromise
256
257        [issuer_sect]
258        C=UK
259        O=Organisation
260        CN=Some Name
261
262   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
267       The names "reasons" and "CRLissuer" are not recognized.
268
269       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
272       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
276       Example:
277
278        issuingDistributionPoint=critical, @idp_section
279
280        [idp_section]
281
282        fullname=URI:http://myhost.com/myca.crl
283        indirectCRL=TRUE
284        onlysomereasons=keyCompromise, CACompromise
285
286        [issuer_sect]
287        C=UK
288        O=Organisation
289        CN=Some Name
290
291   Certificate Policies.
292       This is a raw extension. All the fields of this extension can be set by
293       using the appropriate syntax.
294
295       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
299        certificatePolicies= 1.2.4.5, 1.1.3.4
300
301       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
305       The section referred to must include the policy OID using the name
306       policyIdentifier, cPSuri qualifiers can be included using the syntax:
307
308        CPS.nnn=value
309
310       userNotice qualifiers can be set using the syntax:
311
312        userNotice.nnn=@notice
313
314       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
323       Example:
324
325        certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
326
327        [polsect]
328
329        policyIdentifier = 1.3.5.8
330        CPS.1="http://my.host.name/"
331        CPS.2="http://my.your.name/"
332        userNotice.1=@notice
333
334        [notice]
335
336        explicitText="Explicit Text Here"
337        organization="Organisation Name"
338        noticeNumbers=1,2,3,4
339
340       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
345       ASN1 type of explicitText can be specified by prepending UTF8, BMP or
346       VISIBLE prefix followed by colon. For example:
347
348        [notice]
349        explicitText="UTF8:Explicit Text Here"
350
351   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
356       Example:
357
358        policyConstraints = requireExplicitPolicy:3
359
360   Inhibit Any Policy
361       This is a string extension whose value must be a non negative integer.
362
363       Example:
364
365        inhibitAnyPolicy = 2
366
367   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
374       Examples:
375
376        nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
377
378        nameConstraints=permitted;email:.somedomain.com
379
380        nameConstraints=excluded;email:.com
381
382   OCSP No Check
383       The OCSP No Check extension is a string extension but its value is
384       ignored.
385
386       Example:
387
388        noCheck = ignored
389
390   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
396       The supported names are: status_request and status_request_v2.
397
398       Example:
399
400        tlsfeature = status_request
401

DEPRECATED EXTENSIONS

403       The following extensions are non standard, Netscape specific and
404       largely obsolete. Their use in new applications is discouraged.
405
406   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
411       Example:
412
413        nsComment = "Some Random Comment"
414
415       Other supported extensions in this category are: nsBaseUrl,
416       nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and
417       nsSslServerName.
418
419   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
425       Acceptable values for nsCertType are: client, server, email, objsign,
426       reserved, sslCA, emailCA, objCA.
427

ARBITRARY EXTENSIONS

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
435       There are two ways to encode arbitrary extensions.
436
437       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
440        1.2.3.4=critical,ASN1:UTF8String:Some random data
441
442        1.2.3.4=ASN1:SEQUENCE:seq_sect
443
444        [seq_sect]
445
446        field1 = UTF8:field1
447        field2 = UTF8:field2
448
449       It is also possible to use the word DER to include the raw encoded data
450       in any extension.
451
452        1.2.3.4=critical,DER:01:02:03:04
453        1.2.3.4=DER:01020304
454
455       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
459        basicConstraints=critical,DER:00:01:02:03
460

WARNINGS

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
468       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

NOTES

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
476        subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
477
478       will produce an error but the equivalent form:
479
480        subjectAltName=@subject_alt_section
481
482        [subject_alt_section]
483        subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
484
485       is valid.
486
487       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
490        subjectAltName=@alt_section
491
492        [alt_section]
493
494        email=steve@here
495        email=steve@there
496
497       will only recognize the last value. This can be worked around by using
498       the form:
499
500        [alt_section]
501
502        email.1=steve@here
503        email.2=steve@there
504

SEE ALSO

506       req(1), ca(1), x509(1), ASN1_generate_nconf(3)
507
509       Copyright 2004-2019 The OpenSSL Project Authors. All Rights Reserved.
510
511       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>.
515
516
517
5181.1.1d                            2019-10-03                  X509V3_CONFIG(5)
Impressum