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 exten‐
13 sion 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 ARBITRART 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
61 is a CA certificate. The first (mandatory) name is CA followed by TRUE
62 or FALSE. If CA is TRUE then an optional pathlen name followed by an
63 non-negative value can be included.
64 For example:
66 basicConstraints=CA:TRUE
68 basicConstraints=CA:FALSE
70 basicConstraints=critical,CA:TRUE, pathlen:0
72 A CA certificate must include the basicConstraints value with the CA
74 field set to TRUE. An end user certificate must either set CA to FALSE
75 or exclude the extension entirely. Some software may require the inclu‐
76 sion of basicConstraints with CA set to FALSE for end entity certifi‐
77 cates.
78 The pathlen parameter indicates the maximum number of CAs that can
80 appear below this one in a chain. So if you have a CA with a pathlen of
81 zero it can only be used to sign end user certificates and not further
82 CAs.
83 Key Usage.
85 Key usage is a multi valued extension consisting of a list of names of
87 the permitted key usages.
88 The supporte names are: digitalSignature, nonRepudiation, keyEncipher‐
90 ment, dataEncipherment, keyAgreement, keyCertSign, cRLSign, enci‐
91 pherOnly and decipherOnly.
92 Examples:
94 keyUsage=digitalSignature, nonRepudiation
96 keyUsage=critical, keyCertSign
98 Extended Key Usage.
100 This extensions consists of a list of usages indicating purposes for
102 which the certificate public key can be used for,
103 These can either be object short names of the dotted numerical form of
105 OIDs. While any OID can be used only certain values make sense. In
106 particular the following PKIX, NS and MS values are meaningful:
107 Value Meaning
109 ----- -------
110 serverAuth SSL/TLS Web Server Authentication.
111 clientAuth SSL/TLS Web Client Authentication.
112 codeSigning Code signing.
113 emailProtection E-mail Protection (S/MIME).
114 timeStamping Trusted Timestamping
115 msCodeInd Microsoft Individual Code Signing (authenticode)
116 msCodeCom Microsoft Commercial Code Signing (authenticode)
117 msCTLSign Microsoft Trust List Signing
118 msSGC Microsoft Server Gated Crypto
119 msEFS Microsoft Encrypted File System
120 nsSGC Netscape Server Gated Crypto
121 Examples:
123 extendedKeyUsage=critical,codeSigning,1.2.3.4
125 extendedKeyUsage=nsSGC,msSGC
126 Subject Key Identifier.
128 This is really a string extension and can take two possible values.
130 Either the word hash which will automatically follow the guidelines in
131 RFC3280 or a hex string giving the extension value to include. The use
132 of the hex string is strongly discouraged.
133 Example:
135 subjectKeyIdentifier=hash
137 Authority Key Identifier.
139 The authority key identifier extension permits two options. keyid and
141 issuer: both can take the optional value "always".
142 If the keyid option is present an attempt is made to copy the subject
144 key identifier from the parent certificate. If the value "always" is
145 present then an error is returned if the option fails.
146 The issuer option copies the issuer and serial number from the issuer
148 certificate. This will only be done if the keyid option fails or is not
149 included unless the "always" flag will always include the value.
150 Example:
152 authorityKeyIdentifier=keyid,issuer
154 Subject Alternative Name.
156 The subject alternative name extension allows various literal values to
158 be included in the configuration file. These include email (an email
159 address) URI a uniform resource indicator, DNS (a DNS domain name), RID
160 (a registered ID: OBJECT IDENTIFIER), IP (an IP address), dirName (a
161 distinguished name) and otherName.
162 The email option include a special 'copy' value. This will automati‐
164 cally include and email addresses contained in the certificate subject
165 name in the extension.
166 The IP address used in the IP options can be in either IPv4 or IPv6
168 format.
169 The value of dirName should point to a section containing the distin‐
171 guished name to use as a set of name value pairs. Multi values AVAs can
172 be formed by preceeding the name with a + character.
173 otherName can include arbitrary data associated with an OID: the value
175 should be the OID followed by a semicolon and the content in standard
176 ASN1_generate_nconf() format.
177 Examples:
179 subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/
181 subjectAltName=IP:192.168.7.1
182 subjectAltName=IP:13::17
183 subjectAltName=email:my@other.address,RID:1.2.3.4
184 subjectAltName=otherName:1.2.3.4;UTF8:some other identifier
185 subjectAltName=dirName:dir_sect
187 [dir_sect]
189 C=UK
190 O=My Organization
191 OU=My Unit
192 CN=My Name
193 Issuer Alternative Name.
195 The issuer alternative name option supports all the literal options of
197 subject alternative name. It does not support the email:copy option
198 because that would not make sense. It does support an additional
199 issuer:copy option that will copy all the subject alternative name val‐
200 ues from the issuer certificate (if possible).
201 Example:
203 issuserAltName = issuer:copy
205 Authority Info Access.
207 The authority information access extension gives details about how to
209 access certain information relating to the CA. Its syntax is acces‐
210 sOID;location where location has the same syntax as subject alternative
211 name (except that email:copy is not supported). accessOID can be any
212 valid OID but only certain values are meaningful, for example OCSP and
213 caIssuers.
214 Example:
216 authorityInfoAccess = OCSP;URI:http://ocsp.my.host/
218 authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html
219 CRL distribution points.
221 This is a multi-valued extension that supports all the literal options
223 of subject alternative name. Of the few software packages that cur‐
224 rently interpret this extension most only interpret the URI option.
225 Currently each option will set a new DistributionPoint with the full‐
227 Name field set to the given value.
228 Other fields like cRLissuer and reasons cannot currently be set or dis‐
230 played: at this time no examples were available that used these fields.
231 Examples:
233 crlDistributionPoints=URI:http://myhost.com/myca.crl
235 crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl
236 Certificate Policies.
238 This is a raw extension. All the fields of this extension can be set by
240 using the appropriate syntax.
241 If you follow the PKIX recommendations and just using one OID then you
243 just include the value of that OID. Multiple OIDs can be set separated
244 by commas, for example:
245 certificatePolicies= 1.2.4.5, 1.1.3.4
247 If you wish to include qualifiers then the policy OID and qualifiers
249 need to be specified in a separate section: this is done by using the
250 @section syntax instead of a literal OID value.
251 The section referred to must include the policy OID using the name pol‐
253 icyIdentifier, cPSuri qualifiers can be included using the syntax:
254 CPS.nnn=value
256 userNotice qualifiers can be set using the syntax:
258 userNotice.nnn=@notice
260 The value of the userNotice qualifier is specified in the relevant sec‐
262 tion. This section can include explicitText, organization and noti‐
263 ceNumbers options. explicitText and organization are text strings,
264 noticeNumbers is a comma separated list of numbers. The organization
265 and noticeNumbers options (if included) must BOTH be present. If you
266 use the userNotice option with IE5 then you need the 'ia5org' option at
267 the top level to modify the encoding: otherwise it will not be inter‐
268 preted properly.
269 Example:
271 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect
273 [polsect]
275 policyIdentifier = 1.3.5.8
277 CPS.1="http://my.host.name/"
278 CPS.2="http://my.your.name/"
279 userNotice.1=@notice
280 [notice]
282 explicitText="Explicit Text Here"
284 organization="Organisation Name"
285 noticeNumbers=1,2,3,4
286 The ia5org option changes the type of the organization field. In
288 RFC2459 it can only be of type DisplayText. In RFC3280 IA5Strring is
289 also permissible. Some software (for example some versions of MSIE)
290 may require ia5org.
291 Policy Constraints
293 This is a multi-valued extension which consisting of the names require‐
295 ExplicitPolicy or inhibitPolicyMapping and a non negative intger value.
296 At least one component must be present.
297 Example:
299 policyConstraints = requireExplicitPolicy:3
301 Inhibit Any Policy
303 This is a string extension whose value must be a non negative integer.
305 Example:
307 inhibitAnyPolicy = 2
309 Name Constraints
311 The name constraints extension is a multi-valued extension. The name
313 should begin with the word permitted or excluded followed by a ;. The
314 rest of the name and the value follows the syntax of subjectAltName
315 except email:copy is not supported and the IP form should consist of an
316 IP addresses and subnet mask separated by a /.
317 Examples:
319 nameConstraints=permitted;IP:192.168.0.0/255.255.0.0
321 nameConstraints=permitted;email:.somedomain.com
323 nameConstraints=excluded;email:.com
325
327 The following extensions are non standard, Netscape specific and
328 largely obsolete. Their use in new applications is discouraged.
329 Netscape String extensions.
331 Netscape Comment (nsComment) is a string extension containing a comment
333 which will be displayed when the certificate is viewed in some
334 browsers.
335 Example:
337 nsComment = "Some Random Comment"
339 Other supported extensions in this category are: nsBaseUrl, nsRevoca‐
341 tionUrl, nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl and
342 nsSslServerName.
343 Netscape Certificate Type
345 This is a multi-valued extensions which consists of a list of flags to
347 be included. It was used to indicate the purposes for which a certifi‐
348 cate could be used. The basicConstraints, keyUsage and extended key
349 usage extensions are now used instead.
350 Acceptable values for nsCertType are: client, server, email, objsign,
352 reserved, sslCA, emailCA, objCA.
353
355 If an extension is not supported by the OpenSSL code then it must be
356 encoded using the arbitrary extension format. It is also possible to
357 use the arbitrary format for supported extensions. Extreme care should
358 be taken to ensure that the data is formatted correctly for the given
359 extension type.
360 There are two ways to encode arbitrary extensions.
362 The first way is to use the word ASN1 followed by the extension content
364 using the same syntax as ASN1_generate_nconf(). For example:
365 1.2.3.4=critical,ASN1:UTF8String:Some random data
367 1.2.3.4=ASN1:SEQUENCE:seq_sect
369 [seq_sect]
371 field1 = UTF8:field1
373 field2 = UTF8:field2
374 It is also possible to use the word DER to include the raw encoded data
376 in any extension.
377 1.2.3.4=critical,DER:01:02:03:04
379 1.2.3.4=DER:01020304
380 The value following DER is a hex dump of the DER encoding of the exten‐
382 sion Any extension can be placed in this form to override the default
383 behaviour. For example:
384 basicConstraints=critical,DER:00:01:02:03
386
388 There is no guarantee that a specific implementation will process a
389 given extension. It may therefore be sometimes possible to use certifi‐
390 cates for purposes prohibited by their extensions because a specific
391 application does not recognize or honour the values of the relevant
392 extensions.
393 The DER and ASN1 options should be used with caution. It is possible to
395 create totally invalid extensions if they are not used carefully.
396
398 If an extension is multi-value and a field value must contain a comma
399 the long form must be used otherwise the comma would be misinterpreted
400 as a field separator. For example:
401 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
403 will produce an error but the equivalent form:
405 subjectAltName=@subject_alt_section
407 [subject_alt_section]
409 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar
410 is valid.
412 Due to the behaviour of the OpenSSL conf library the same field name
414 can only occur once in a section. This means that:
415 subjectAltName=@alt_section
417 [alt_section]
419 email=steve@here
421 email=steve@there
422 will only recognize the last value. This can be worked around by using
424 the form:
425 [alt_section]
427 email.1=steve@here
429 email.2=steve@there
430
432 The X509v3 extension code was first added to OpenSSL 0.9.2.
433 Policy mappings, inhibit any policy and name constraints support was
435 added in OpenSSL 0.9.8
436 The directoryName and otherName option as well as the ASN1 option for
438 arbitrary extensions was added in OpenSSL 0.9.8
439
441 req(1), ca(1), x509(1)
4420.9.8b 2005-06-22 X509V3_CONFIG(5)