]>
Commit | Line | Data |
---|---|---|
19f39703 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | x509v3_config - X509 V3 certificate extension configuration format | |
6 | ||
7 | =head1 DESCRIPTION | |
8 | ||
eaf8ec1a | 9 | Several OpenSSL commands can add extensions to a certificate or |
19f39703 | 10 | certificate request based on the contents of a configuration file. |
eaf8ec1a RS |
11 | The syntax of this file is described in L<config(5)>. |
12 | The commands typically have an option to specify the name of the configuration | |
13 | file, and a section within that file; see the documentation of the | |
14 | individual command for details. | |
19f39703 | 15 | |
eaf8ec1a RS |
16 | This page uses B<extensions> as the name of the section, when needed |
17 | in examples. | |
19f39703 | 18 | |
eaf8ec1a | 19 | Each entry in the extension section takes the form: |
19f39703 | 20 | |
eaf8ec1a | 21 | name = [critical, ]value(s) |
19f39703 | 22 | |
eaf8ec1a | 23 | If B<critical> is present then the extension will be marked as critical. |
19f39703 | 24 | |
eaf8ec1a RS |
25 | The format of B<values> depends on the value of B<name>, many have a |
26 | type-value pairing where the type and value are separated by a colon. | |
27 | There are four main types of extension: | |
19f39703 | 28 | |
eaf8ec1a RS |
29 | string |
30 | multi-valued | |
31 | raw | |
32 | arbitrary | |
19f39703 | 33 | |
eaf8ec1a | 34 | Each is described in the following paragraphs. |
19f39703 | 35 | |
eaf8ec1a RS |
36 | String extensions simply have a string which contains either the value itself |
37 | or how it is obtained. | |
19f39703 DSH |
38 | |
39 | Multi-valued extensions have a short form and a long form. The short form | |
eaf8ec1a | 40 | is a commma-separated list of names and values: |
19f39703 | 41 | |
eaf8ec1a | 42 | basicConstraints = critical, CA:true, pathlen:1 |
19f39703 DSH |
43 | |
44 | The long form allows the values to be placed in a separate section: | |
45 | ||
eaf8ec1a RS |
46 | [extensions] |
47 | basicConstraints = critical, @basic_constraints | |
19f39703 | 48 | |
eaf8ec1a RS |
49 | [basic_constraints] |
50 | CA = true | |
51 | pathlen = 1 | |
19f39703 DSH |
52 | |
53 | Both forms are equivalent. | |
54 | ||
eaf8ec1a RS |
55 | If an extension is multi-value and a field value must contain a comma the long |
56 | form must be used otherwise the comma would be misinterpreted as a field | |
57 | separator. For example: | |
58 | ||
59 | subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar | |
60 | ||
61 | will produce an error but the equivalent form: | |
62 | ||
63 | [extensions] | |
64 | subjectAltName = @subject_alt_section | |
65 | ||
66 | [subject_alt_section] | |
67 | subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar | |
68 | ||
69 | is valid. | |
70 | ||
71 | OpenSSL does not support multiple occurences of the same field within a | |
72 | section. In this example: | |
73 | ||
74 | [extensions] | |
75 | subjectAltName = @alt_section | |
76 | ||
77 | [alt_section] | |
78 | email = steve@here | |
79 | email = steve@there | |
80 | ||
81 | will only recognize the last value. To specify multiple values append a | |
82 | numeric identifier, as shown here: | |
83 | ||
84 | [extensions] | |
85 | subjectAltName = @alt_section | |
86 | ||
87 | [alt_section] | |
88 | email.1 = steve@here | |
89 | email.2 = steve@there | |
90 | ||
91 | The syntax of raw extensions is defined by the source code that parses | |
92 | the extension but should be documened. | |
93 | See L</Certificate Policies> for an example of a raw extension. | |
19f39703 | 94 | |
eaf8ec1a | 95 | If an extension type is unsupported, then the I<arbitrary> extension syntax |
6e4618a0 | 96 | must be used, see the L</ARBITRARY EXTENSIONS> section for more details. |
19f39703 DSH |
97 | |
98 | =head1 STANDARD EXTENSIONS | |
99 | ||
eaf8ec1a RS |
100 | The following sections describe the syntax of each supported extension. |
101 | They do not define the semantics of the extension. | |
19f39703 | 102 | |
485d3361 | 103 | =head2 Basic Constraints |
19f39703 | 104 | |
eaf8ec1a RS |
105 | This is a multi-valued extension which indicates whether a certificate is |
106 | a CA certificate. The first value is B<CA> followed by B<TRUE> or | |
21542a48 | 107 | B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by a |
19f39703 DSH |
108 | non-negative value can be included. |
109 | ||
110 | For example: | |
111 | ||
eaf8ec1a | 112 | basicConstraints = CA:TRUE |
19f39703 | 113 | |
eaf8ec1a | 114 | basicConstraints = CA:FALSE |
19f39703 | 115 | |
eaf8ec1a | 116 | basicConstraints = critical, CA:TRUE, pathlen:1 |
19f39703 | 117 | |
eaf8ec1a RS |
118 | A CA certificate I<must> include the B<basicConstraints> name with the B<CA> |
119 | parameter set to B<TRUE>. An end-user certificate must either have B<CA:FALSE> | |
120 | or omit the extension entirely. | |
121 | The B<pathlen> parameter specifies the maximum number of CAs that can appear | |
122 | below this one in a chain. A B<pathlen> of zero means the CA cannot sign | |
123 | any sub-CA's, and can only sign end-entity certificates. | |
19f39703 | 124 | |
485d3361 | 125 | =head2 Key Usage |
19f39703 | 126 | |
eaf8ec1a RS |
127 | Key usage is a multi-valued extension consisting of a list of names of |
128 | the permitted key usages. The defined values are: C<digitalSignature>, | |
129 | C<nonRepudiation>, C<keyEncipherment>, C<dataEncipherment>, C<keyAgreement>, | |
130 | C<keyCertSign>, C<cRLSign>, C<encipherOnly>, and C<decipherOnly>. | |
19f39703 DSH |
131 | |
132 | Examples: | |
133 | ||
eaf8ec1a | 134 | keyUsage = digitalSignature, nonRepudiation |
19f39703 | 135 | |
eaf8ec1a | 136 | keyUsage = critical, keyCertSign |
19f39703 | 137 | |
485d3361 | 138 | =head2 Extended Key Usage |
19f39703 | 139 | |
eaf8ec1a RS |
140 | This extension consists of a list of values indicating purposes for which |
141 | the certificate public key can be used for, Each value can be either a | |
142 | short text name or an OID. | |
143 | The following text names, and their intended meaning, are known: | |
19f39703 | 144 | |
1bc74519 RS |
145 | Value Meaning |
146 | ----- ------- | |
eaf8ec1a RS |
147 | serverAuth SSL/TLS Web Server Authentication |
148 | clientAuth SSL/TLS Web Client Authentication | |
149 | codeSigning Code signing | |
150 | emailProtection E-mail Protection (S/MIME) | |
1bc74519 RS |
151 | timeStamping Trusted Timestamping |
152 | OCSPSigning OCSP Signing | |
0ad69cd6 | 153 | ipsecIKE ipsec Internet Key Exchange |
1bc74519 RS |
154 | msCodeInd Microsoft Individual Code Signing (authenticode) |
155 | msCodeCom Microsoft Commercial Code Signing (authenticode) | |
156 | msCTLSign Microsoft Trust List Signing | |
157 | msEFS Microsoft Encrypted File System | |
19f39703 DSH |
158 | |
159 | Examples: | |
160 | ||
eaf8ec1a | 161 | extendedKeyUsage = critical, codeSigning, 1.2.3.4 |
19f39703 | 162 | |
eaf8ec1a | 163 | extendedKeyUsage = serverAuth, clientAuth |
19f39703 | 164 | |
485d3361 | 165 | =head2 Subject Key Identifier |
19f39703 | 166 | |
eaf8ec1a RS |
167 | This is a string extension with one of two legal values. If it is the word |
168 | B<hash>, then OpenSSL will follow the process in RFC 5280 to calculate the | |
169 | hash value. | |
170 | Otherwise, the value should be a hex string to output directly, however this | |
171 | is strongly discouraged. | |
19f39703 DSH |
172 | |
173 | Example: | |
174 | ||
eaf8ec1a | 175 | subjectKeyIdentifier = hash |
19f39703 | 176 | |
485d3361 | 177 | =head2 Authority Key Identifier |
19f39703 | 178 | |
eaf8ec1a RS |
179 | This extension has two options, B<keyid> and B<issuer>. Either or both |
180 | can have the value B<always>, indicated by putting a colon between | |
181 | the option and its value. | |
19f39703 | 182 | |
eaf8ec1a RS |
183 | If B<keyid> is present, than an attempt is made to copy the subject key |
184 | identifier from the parent certificate. If the value B<always> is present, | |
185 | then an error can be returned if the option fails. If B<issuer> is present, | |
186 | an attempt is made to copy the issuer and serial number from the parent | |
187 | certificate. This is done if the B<keyid> option fails, or if B<issuer> | |
188 | has B<always> specified. | |
5dd87981 | 189 | |
eaf8ec1a | 190 | Examples: |
5dd87981 | 191 | |
eaf8ec1a | 192 | authorityKeyIdentifier = keyid, issuer |
19f39703 | 193 | |
eaf8ec1a | 194 | authorityKeyIdentifier = keyid, issuer:always |
19f39703 | 195 | |
485d3361 | 196 | =head2 Subject Alternative Name |
19f39703 | 197 | |
eaf8ec1a RS |
198 | This is a multi-valued extension that supports several types of name |
199 | identifier, including | |
200 | B<email> (an email address), | |
201 | B<URI> (a uniform resource indicator), | |
202 | B<DNS> (a DNS domain name), | |
203 | B<RID> (a registered ID: OBJECT IDENTIFIER), | |
204 | B<IP> (an IP address), | |
205 | B<dirName> (a distinguished name), | |
206 | and B<otherName>. | |
207 | The syntax of each is described in the following paragraphs. | |
208 | ||
209 | The B<email> option has a special C<copy> value, which will automatically | |
a41815f0 | 210 | include any email addresses contained in the certificate subject name in |
19f39703 DSH |
211 | the extension. |
212 | ||
eaf8ec1a | 213 | The IP address used in the B<IP> option can be in either IPv4 or IPv6 format. |
37dccd8f | 214 | |
eaf8ec1a RS |
215 | The value of B<dirName> is specifies the configuration section containing |
216 | the distinguished name to use, as a set of name-value pairs. | |
217 | Multi-valued AVAs can be formed by prefacing the name with a B<+> character. | |
19f39703 | 218 | |
eaf8ec1a RS |
219 | The value of B<otherName> can include arbitrary data associated with an OID; |
220 | the value should be the OID followed by a semicolon and the content in specified | |
221 | using the syntax in L<ASN1_generate_nconf(3)>. | |
19f39703 DSH |
222 | |
223 | Examples: | |
224 | ||
eaf8ec1a | 225 | subjectAltName = email:copy, email:my@other.address, URI:http://my.url.here/ |
19f39703 | 226 | |
eaf8ec1a | 227 | subjectAltName = IP:192.168.7.1 |
19f39703 | 228 | |
eaf8ec1a RS |
229 | subjectAltName = IP:13::17 |
230 | ||
231 | subjectAltName = email:my@other.address, RID:1.2.3.4 | |
232 | ||
233 | subjectAltName = otherName:1.2.3.4;UTF8:some other identifier | |
19f39703 | 234 | |
eaf8ec1a RS |
235 | [extensions] |
236 | subjectAltName = dirName:dir_sect | |
237 | ||
238 | [dir_sect] | |
239 | C = UK | |
240 | O = My Organization | |
241 | OU = My Unit | |
242 | CN = My Name | |
19f39703 | 243 | |
485d3361 | 244 | =head2 Issuer Alternative Name |
19f39703 | 245 | |
eaf8ec1a RS |
246 | This extension supports most of the options of subject alternative name; |
247 | it does not support B<email:copy>. | |
248 | It also adds B<issuer:copy> as an allowed value, which copies any subject | |
249 | alternative names from the issuer certificate, if possible. | |
19f39703 DSH |
250 | |
251 | Example: | |
252 | ||
36cf10cf | 253 | issuerAltName = issuer:copy |
19f39703 | 254 | |
485d3361 | 255 | =head2 Authority Info Access |
19f39703 | 256 | |
eaf8ec1a RS |
257 | This extension gives details about how to retrieve information that |
258 | related to the certificate that the CA makes available. The syntax is | |
259 | B<access_id;location>, where B<access_id> is an object identifier | |
260 | (although only a few values are well-known) and B<location> has the same | |
261 | syntax as subject alternative name (except that B<email:copy> is not supported). | |
19f39703 | 262 | |
eaf8ec1a | 263 | Examples: |
19f39703 DSH |
264 | |
265 | authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ | |
19f39703 | 266 | |
05ea606a | 267 | =head2 CRL distribution points |
19f39703 | 268 | |
eaf8ec1a RS |
269 | This is a multi-valued extension whose values can be either a name-value |
270 | pair using the same form as subject alternative name or a single value | |
271 | specifying the section name containing all the distribution point values. | |
272 | ||
273 | When a name-value pair is used, a DistributionPoint extension will | |
274 | be set with the given value as the fullName field as the distributionPoint | |
275 | value, and the reasons and cRLIssuer fields will be omitted. | |
276 | ||
277 | When a single option is used, the value specifies the section, and that | |
278 | section can have the following items: | |
279 | ||
280 | =over 4 | |
281 | ||
282 | =item fullname | |
283 | ||
284 | The full name of the distribution point, in the same format as the subject | |
285 | alternative name. | |
286 | ||
287 | =item relativename | |
19f39703 | 288 | |
eaf8ec1a RS |
289 | The value is taken as a distinguished name fragment that is set as the |
290 | value of the nameRelativeToCRLIssuer field. | |
19f39703 | 291 | |
eaf8ec1a | 292 | =item CRLIssuer |
19f39703 | 293 | |
eaf8ec1a | 294 | The value must in the same format as the subject alternative name. |
83357f04 | 295 | |
eaf8ec1a | 296 | =item reasons |
83357f04 | 297 | |
eaf8ec1a RS |
298 | A multi-value field that contains the reasons for revocation. The recognized |
299 | values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>, | |
300 | C<superseded>, C<cessationOfOperation>, C<certificateHold>, | |
301 | C<privilegeWithdrawn>, and C<AACompromise>. | |
83357f04 | 302 | |
eaf8ec1a | 303 | =back |
83357f04 | 304 | |
eaf8ec1a | 305 | Only one of B<fullname> or B<relativename> should be specified. |
83357f04 DSH |
306 | |
307 | Simple examples: | |
19f39703 | 308 | |
eaf8ec1a RS |
309 | crlDistributionPoints = URI:http://myhost.com/myca.crl |
310 | ||
311 | crlDistributionPoints = URI:http://my.com/my.crl, URI:http://oth.com/my.crl | |
19f39703 | 312 | |
83357f04 DSH |
313 | Full distribution point example: |
314 | ||
eaf8ec1a RS |
315 | [extensions] |
316 | crlDistributionPoints = crldp1_section | |
83357f04 DSH |
317 | |
318 | [crldp1_section] | |
eaf8ec1a RS |
319 | fullname = URI:http://myhost.com/myca.crl |
320 | CRLissuer = dirName:issuer_sect | |
321 | reasons = keyCompromise, CACompromise | |
83357f04 DSH |
322 | |
323 | [issuer_sect] | |
eaf8ec1a RS |
324 | C = UK |
325 | O = Organisation | |
326 | CN = Some Name | |
83357f04 DSH |
327 | |
328 | =head2 Issuing Distribution Point | |
329 | ||
eaf8ec1a | 330 | This extension should only appear in CRLs. It is a multi-valued extension |
83357f04 | 331 | whose syntax is similar to the "section" pointed to by the CRL distribution |
eaf8ec1a | 332 | points extension. The following names have meaning: |
83357f04 | 333 | |
eaf8ec1a | 334 | =over 4 |
83357f04 | 335 | |
eaf8ec1a | 336 | =item fullname |
83357f04 | 337 | |
eaf8ec1a RS |
338 | The full name of the distribution point, in the same format as the subject |
339 | alternative name. | |
83357f04 | 340 | |
eaf8ec1a | 341 | =item relativename |
83357f04 | 342 | |
eaf8ec1a RS |
343 | The value is taken as a distinguished name fragment that is set as the |
344 | value of the nameRelativeToCRLIssuer field. | |
83357f04 | 345 | |
eaf8ec1a | 346 | =item onlysomereasons |
83357f04 | 347 | |
eaf8ec1a RS |
348 | A multi-value field that contains the reasons for revocation. The recognized |
349 | values are: C<keyCompromise>, C<CACompromise>, C<affiliationChanged>, | |
350 | C<superseded>, C<cessationOfOperation>, C<certificateHold>, | |
351 | C<privilegeWithdrawn>, and C<AACompromise>. | |
83357f04 | 352 | |
eaf8ec1a RS |
353 | =item onlyuser, onlyCA, onlyAA, indirectCRL |
354 | ||
355 | The value for each of these names is a boolean. | |
83357f04 | 356 | |
eaf8ec1a RS |
357 | =back |
358 | ||
359 | Example: | |
360 | ||
361 | [extensions] | |
362 | issuingDistributionPoint = critical, @idp_section | |
363 | ||
364 | [idp_section] | |
365 | fullname = URI:http://myhost.com/myca.crl | |
366 | indirectCRL = TRUE | |
367 | onlysomereasons = keyCompromise, CACompromise | |
085ccc54 | 368 | |
485d3361 | 369 | =head2 Certificate Policies |
19f39703 | 370 | |
eaf8ec1a RS |
371 | This is a I<raw> extension that supports all of the defined fields of the |
372 | certificate extension. | |
19f39703 | 373 | |
eaf8ec1a RS |
374 | Policies without qualifiers are specified by giving the OID. |
375 | Multiple policies are comma-separated. For example: | |
19f39703 | 376 | |
eaf8ec1a | 377 | certificatePolicies = 1.2.4.5, 1.1.3.4 |
19f39703 | 378 | |
eaf8ec1a RS |
379 | To include policy qualifiers, use the "@section" syntax to point to a |
380 | section that specifies all the information. | |
19f39703 DSH |
381 | |
382 | The section referred to must include the policy OID using the name | |
eaf8ec1a RS |
383 | B<policyIdentifier>. cPSuri qualifiers can be included using the syntax: |
384 | ||
385 | CPS.nnn = value | |
19f39703 | 386 | |
eaf8ec1a | 387 | where C<nnn> is a number. |
19f39703 DSH |
388 | |
389 | userNotice qualifiers can be set using the syntax: | |
390 | ||
eaf8ec1a | 391 | userNotice.nnn = @notice |
19f39703 DSH |
392 | |
393 | The value of the userNotice qualifier is specified in the relevant section. | |
eaf8ec1a | 394 | This section can include B<explicitText>, B<organization>, and B<noticeNumbers> |
19f39703 DSH |
395 | options. explicitText and organization are text strings, noticeNumbers is a |
396 | comma separated list of numbers. The organization and noticeNumbers options | |
eaf8ec1a RS |
397 | (if included) must BOTH be present. Some software might require |
398 | the B<ia5org> option at the top level; this changes the encoding from | |
399 | Displaytext to IA5String. | |
19f39703 DSH |
400 | |
401 | Example: | |
402 | ||
eaf8ec1a RS |
403 | [extensions] |
404 | certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect | |
19f39703 DSH |
405 | |
406 | [polsect] | |
19f39703 | 407 | policyIdentifier = 1.3.5.8 |
eaf8ec1a RS |
408 | CPS.1 = "http://my.host.name/" |
409 | CPS.2 = "http://my.your.name/" | |
410 | userNotice.1 = @notice | |
19f39703 DSH |
411 | |
412 | [notice] | |
eaf8ec1a RS |
413 | explicitText = "Explicit Text Here" |
414 | organization = "Organisation Name" | |
415 | noticeNumbers = 1, 2, 3, 4 | |
19f39703 | 416 | |
eaf8ec1a RS |
417 | The character encoding of explicitText can be specified by prefixing the |
418 | value with B<UTF8>, B<BMP>, or B<VISIBLE> followed by colon. For example: | |
0444c52a MK |
419 | |
420 | [notice] | |
eaf8ec1a | 421 | explicitText = "UTF8:Explicit Text Here" |
0444c52a | 422 | |
37dccd8f DSH |
423 | =head2 Policy Constraints |
424 | ||
425 | This is a multi-valued extension which consisting of the names | |
4c583c36 | 426 | B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative integer |
37dccd8f DSH |
427 | value. At least one component must be present. |
428 | ||
429 | Example: | |
430 | ||
431 | policyConstraints = requireExplicitPolicy:3 | |
432 | ||
37dccd8f DSH |
433 | =head2 Inhibit Any Policy |
434 | ||
435 | This is a string extension whose value must be a non negative integer. | |
436 | ||
437 | Example: | |
438 | ||
439 | inhibitAnyPolicy = 2 | |
440 | ||
5dd87981 DSH |
441 | =head2 Name Constraints |
442 | ||
eaf8ec1a | 443 | This is a multi-valued extension. The name should |
5dd87981 | 444 | begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of |
eaf8ec1a RS |
445 | the name and the value follows the syntax of subjectAltName except |
446 | B<email:copy> | |
4c583c36 | 447 | is not supported and the B<IP> form should consist of an IP addresses and |
5dd87981 DSH |
448 | subnet mask separated by a B</>. |
449 | ||
450 | Examples: | |
451 | ||
eaf8ec1a | 452 | nameConstraints = permitted;IP:192.168.0.0/255.255.0.0 |
5dd87981 | 453 | |
eaf8ec1a | 454 | nameConstraints = permitted;email:.somedomain.com |
085ccc54 | 455 | |
eaf8ec1a | 456 | nameConstraints = excluded;email:.com |
83357f04 | 457 | |
137de5b1 DSH |
458 | =head2 OCSP No Check |
459 | ||
eaf8ec1a | 460 | This is a string extension. It is parsed, but ignored. |
137de5b1 DSH |
461 | |
462 | Example: | |
463 | ||
464 | noCheck = ignored | |
465 | ||
ba67253d RS |
466 | =head2 TLS Feature (aka Must Staple) |
467 | ||
468 | This is a multi-valued extension consisting of a list of TLS extension | |
469 | identifiers. Each identifier may be a number (0..65535) or a supported name. | |
470 | When a TLS client sends a listed extension, the TLS server is expected to | |
471 | include that extension in its reply. | |
472 | ||
473 | The supported names are: B<status_request> and B<status_request_v2>. | |
474 | ||
475 | Example: | |
476 | ||
477 | tlsfeature = status_request | |
478 | ||
19f39703 DSH |
479 | =head1 DEPRECATED EXTENSIONS |
480 | ||
5dd87981 DSH |
481 | The following extensions are non standard, Netscape specific and largely |
482 | obsolete. Their use in new applications is discouraged. | |
19f39703 | 483 | |
485d3361 | 484 | =head2 Netscape String extensions |
19f39703 DSH |
485 | |
486 | Netscape Comment (B<nsComment>) is a string extension containing a comment | |
487 | which will be displayed when the certificate is viewed in some browsers. | |
eaf8ec1a | 488 | Other extensions of this type are: B<nsBaseUrl>, |
19f39703 DSH |
489 | B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> |
490 | and B<nsSslServerName>. | |
491 | ||
19f39703 DSH |
492 | =head2 Netscape Certificate Type |
493 | ||
494 | This is a multi-valued extensions which consists of a list of flags to be | |
495 | included. It was used to indicate the purposes for which a certificate could | |
496 | be used. The basicConstraints, keyUsage and extended key usage extensions are | |
497 | now used instead. | |
498 | ||
499 | Acceptable values for nsCertType are: B<client>, B<server>, B<email>, | |
500 | B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. | |
501 | ||
19f39703 DSH |
502 | =head1 ARBITRARY EXTENSIONS |
503 | ||
504 | If an extension is not supported by the OpenSSL code then it must be encoded | |
505 | using the arbitrary extension format. It is also possible to use the arbitrary | |
506 | format for supported extensions. Extreme care should be taken to ensure that | |
507 | the data is formatted correctly for the given extension type. | |
508 | ||
509 | There are two ways to encode arbitrary extensions. | |
510 | ||
511 | The first way is to use the word ASN1 followed by the extension content | |
9b86974e | 512 | using the same syntax as L<ASN1_generate_nconf(3)>. |
51cc37b6 | 513 | For example: |
19f39703 | 514 | |
eaf8ec1a RS |
515 | [extensions] |
516 | 1.2.3.4 = critical, ASN1:UTF8String:Some random data | |
517 | 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect | |
19f39703 DSH |
518 | |
519 | [seq_sect] | |
19f39703 DSH |
520 | field1 = UTF8:field1 |
521 | field2 = UTF8:field2 | |
522 | ||
523 | It is also possible to use the word DER to include the raw encoded data in any | |
524 | extension. | |
525 | ||
eaf8ec1a RS |
526 | 1.2.3.4 = critical, DER:01:02:03:04 |
527 | 1.2.3.4.1 = DER:01020304 | |
19f39703 DSH |
528 | |
529 | The value following DER is a hex dump of the DER encoding of the extension | |
530 | Any extension can be placed in this form to override the default behaviour. | |
531 | For example: | |
532 | ||
eaf8ec1a | 533 | basicConstraints = critical, DER:00:01:02:03 |
19f39703 | 534 | |
5e0d9c86 | 535 | =head1 WARNINGS |
19f39703 DSH |
536 | |
537 | There is no guarantee that a specific implementation will process a given | |
538 | extension. It may therefore be sometimes possible to use certificates for | |
539 | purposes prohibited by their extensions because a specific application does | |
540 | not recognize or honour the values of the relevant extensions. | |
541 | ||
542 | The DER and ASN1 options should be used with caution. It is possible to create | |
eaf8ec1a | 543 | invalid extensions if they are not used carefully. |
5dd87981 | 544 | |
5dd87981 DSH |
545 | =head1 SEE ALSO |
546 | ||
1903a9b7 | 547 | L<openssl-req(1)>, L<openssl-ca(1)>, L<openssl-x509(1)>, |
9b86974e | 548 | L<ASN1_generate_nconf(3)> |
5dd87981 | 549 | |
e2f92610 RS |
550 | =head1 COPYRIGHT |
551 | ||
33388b44 | 552 | Copyright 2004-2020 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 553 | |
b1e979ae | 554 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
555 | this file except in compliance with the License. You can obtain a copy |
556 | in the file LICENSE in the source distribution or at | |
557 | L<https://www.openssl.org/source/license.html>. | |
558 | ||
5dd87981 | 559 | =cut |