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