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 an
62 non-negative 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 supporte 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 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 Examples:
120 extendedKeyUsage=critical,codeSigning,1.2.3.4
122 extendedKeyUsage=nsSGC,msSGC
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 and 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 issuserAltName = 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 IA5Strring is
342 also permissible. Some software (for example some versions of MSIE)
343 may require ia5org.
344 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 Example:
351 policyConstraints = requireExplicitPolicy:3
353 Inhibit Any Policy
355 This is a string extension whose value must be a non negative integer.
356 Example:
358 inhibitAnyPolicy = 2
360 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 Examples:
369 nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
371 nameConstraints=permitted;email:.somedomain.com
373 nameConstraints=excluded;email:.com
375 OCSP No Check
377 The OCSP No Check extension is a string extension but its value is
378 ignored.
379 Example:
381 noCheck = ignored
383
385 The following extensions are non standard, Netscape specific and
386 largely obsolete. Their use in new applications is discouraged.
387 Netscape String extensions.
389 Netscape Comment (nsComment) is a string extension containing a comment
390 which will be displayed when the certificate is viewed in some
391 browsers.
392 Example:
394 nsComment = "Some Random Comment"
396 Other supported extensions in this category are: nsBaseUrl,
398 nsRevocationUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and
399 nsSslServerName.
400 Netscape Certificate Type
402 This is a multi-valued extensions which consists of a list of flags to
403 be included. It was used to indicate the purposes for which a
404 certificate could be used. The basicConstraints, keyUsage and extended
405 key usage extensions are now used instead.
406 Acceptable values for nsCertType are: client, server, email, objsign,
408 reserved, sslCA, emailCA, objCA.
409
411 If an extension is not supported by the OpenSSL code then it must be
412 encoded using the arbitrary extension format. It is also possible to
413 use the arbitrary format for supported extensions. Extreme care should
414 be taken to ensure that the data is formatted correctly for the given
415 extension type.
416 There are two ways to encode arbitrary extensions.
418 The first way is to use the word ASN1 followed by the extension content
420 using the same syntax as ASN1_generate_nconf(3). For example:
421 1.2.3.4=critical,ASN1:UTF8String:Some random data
423 1.2.3.4=ASN1:SEQUENCE:seq_sect
425 [seq_sect]
427 field1 = UTF8:field1
429 field2 = UTF8:field2
430 It is also possible to use the word DER to include the raw encoded data
432 in any extension.
433 1.2.3.4=critical,DER:01:02:03:04
435 1.2.3.4=DER:01020304
436 The value following DER is a hex dump of the DER encoding of the
438 extension Any extension can be placed in this form to override the
439 default behaviour. For example:
440 basicConstraints=critical,DER:00:01:02:03
442
444 There is no guarantee that a specific implementation will process a
445 given extension. It may therefore be sometimes possible to use
446 certificates for purposes prohibited by their extensions because a
447 specific application does not recognize or honour the values of the
448 relevant extensions.
449 The DER and ASN1 options should be used with caution. It is possible to
451 create totally invalid extensions if they are not used carefully.
452
454 If an extension is multi-value and a field value must contain a comma
455 the long form must be used otherwise the comma would be misinterpreted
456 as a field separator. For example:
457 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
459 will produce an error but the equivalent form:
461 subjectAltName=@subject_alt_section
463 [subject_alt_section]
465 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
466 is valid.
468 Due to the behaviour of the OpenSSL conf library the same field name
470 can only occur once in a section. This means that:
471 subjectAltName=@alt_section
473 [alt_section]
475 email=steve@here
477 email=steve@there
478 will only recognize the last value. This can be worked around by using
480 the form:
481 [alt_section]
483 email.1=steve@here
485 email.2=steve@there
486
488 The X509v3 extension code was first added to OpenSSL 0.9.2.
489 Policy mappings, inhibit any policy and name constraints support was
491 added in OpenSSL 0.9.8
492 The directoryName and otherName option as well as the ASN1 option for
494 arbitrary extensions was added in OpenSSL 0.9.8
495
497 req(1), ca(1), x509(1), ASN1_generate_nconf(3)
4981.0.2k 2017-01-26 X509V3_CONFIG(5)