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 supporte 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 of 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        msCodeInd              Microsoft Individual Code Signing (authenticode)
113        msCodeCom              Microsoft Commercial Code Signing (authenticode)
114        msCTLSign              Microsoft Trust List Signing
115        msSGC                  Microsoft Server Gated Crypto
116        msEFS                  Microsoft Encrypted File System
117        nsSGC                  Netscape Server Gated Crypto
118
119       Examples:
120
121        extendedKeyUsage=critical,codeSigning,1.2.3.4
122        extendedKeyUsage=nsSGC,msSGC
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 and 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 preceeding 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        issuserAltName = 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 IA5Strring is
342       also permissible.  Some software (for example some versions of MSIE)
343       may require ia5org.
344
345   Policy Constraints
346       This is a multi-valued extension which consisting of the names
347       requireExplicitPolicy or inhibitPolicyMapping and a non negative intger
348       value. At least one component must be present.
349
350       Example:
351
352        policyConstraints = requireExplicitPolicy:3
353
354   Inhibit Any Policy
355       This is a string extension whose value must be a non negative integer.
356
357       Example:
358
359        inhibitAnyPolicy = 2
360
361   Name Constraints
362       The name constraints extension is a multi-valued extension. The name
363       should begin with the word permitted or excluded followed by a ;. The
364       rest of the name and the value follows the syntax of subjectAltName
365       except email:copy is not supported and the IP form should consist of an
366       IP addresses and subnet mask separated by a /.
367
368       Examples:
369
370        nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
371
372        nameConstraints=permitted;email:.somedomain.com
373
374        nameConstraints=excluded;email:.com
375       issuingDistributionPoint = idp_section
376
377   OCSP No Check
378       The OCSP No Check extension is a string extension but its value is
379       ignored.
380
381       Example:
382
383        noCheck = ignored
384

DEPRECATED EXTENSIONS

386       The following extensions are non standard, Netscape specific and
387       largely obsolete. Their use in new applications is discouraged.
388
389   Netscape String extensions.
390       Netscape Comment (nsComment) is a string extension containing a comment
391       which will be displayed when the certificate is viewed in some
392       browsers.
393
394       Example:
395
396        nsComment = "Some Random Comment"
397
398       Other supported extensions in this category are: nsBaseUrl,
399       nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and
400       nsSslServerName.
401
402   Netscape Certificate Type
403       This is a multi-valued extensions which consists of a list of flags to
404       be included. It was used to indicate the purposes for which a
405       certificate could be used. The basicConstraints, keyUsage and extended
406       key usage extensions are now used instead.
407
408       Acceptable values for nsCertType are: client, server, email, objsign,
409       reserved, sslCA, emailCA, objCA.
410

ARBITRARY EXTENSIONS

412       If an extension is not supported by the OpenSSL code then it must be
413       encoded using the arbitrary extension format. It is also possible to
414       use the arbitrary format for supported extensions. Extreme care should
415       be taken to ensure that the data is formatted correctly for the given
416       extension type.
417
418       There are two ways to encode arbitrary extensions.
419
420       The first way is to use the word ASN1 followed by the extension content
421       using the same syntax as ASN1_generate_nconf(3).  For example:
422
423        1.2.3.4=critical,ASN1:UTF8String:Some random data
424
425        1.2.3.4=ASN1:SEQUENCE:seq_sect
426
427        [seq_sect]
428
429        field1 = UTF8:field1
430        field2 = UTF8:field2
431
432       It is also possible to use the word DER to include the raw encoded data
433       in any extension.
434
435        1.2.3.4=critical,DER:01:02:03:04
436        1.2.3.4=DER:01020304
437
438       The value following DER is a hex dump of the DER encoding of the
439       extension Any extension can be placed in this form to override the
440       default behaviour.  For example:
441
442        basicConstraints=critical,DER:00:01:02:03
443

WARNING

445       There is no guarantee that a specific implementation will process a
446       given extension. It may therefore be sometimes possible to use
447       certificates for purposes prohibited by their extensions because a
448       specific application does not recognize or honour the values of the
449       relevant extensions.
450
451       The DER and ASN1 options should be used with caution. It is possible to
452       create totally invalid extensions if they are not used carefully.
453

NOTES

455       If an extension is multi-value and a field value must contain a comma
456       the long form must be used otherwise the comma would be misinterpreted
457       as a field separator. For example:
458
459        subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
460
461       will produce an error but the equivalent form:
462
463        subjectAltName=@subject_alt_section
464
465        [subject_alt_section]
466        subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
467
468       is valid.
469
470       Due to the behaviour of the OpenSSL conf library the same field name
471       can only occur once in a section. This means that:
472
473        subjectAltName=@alt_section
474
475        [alt_section]
476
477        email=steve@here
478        email=steve@there
479
480       will only recognize the last value. This can be worked around by using
481       the form:
482
483        [alt_section]
484
485        email.1=steve@here
486        email.2=steve@there
487

HISTORY

489       The X509v3 extension code was first added to OpenSSL 0.9.2.
490
491       Policy mappings, inhibit any policy and name constraints support was
492       added in OpenSSL 0.9.8
493
494       The directoryName and otherName option as well as the ASN1 option for
495       arbitrary extensions was added in OpenSSL 0.9.8
496

SEE ALSO

498       req(1), ca(1), x509(1), ASN1_generate_nconf(3)
499
500
501
5021.0.0e                            2006-11-07                  X509V3_CONFIG(5)
Impressum