Debian Codegraph @

upstream/debian-unstable/man5/x509v3_config.5ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "X509V3_CONFIG 5SSL"
58 .TH X509V3_CONFIG 5SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 x509v3_config \- X509 V3 certificate extension configuration format
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 Several OpenSSL commands can add extensions to a certificate or
68 certificate request based on the contents of a configuration file
69 and CLI options such as \fB\-addext\fR.
70 The syntax of configuration files is described in \fBconfig\fR\|(5).
71 The commands typically have an option to specify the name of the configuration
72 file, and a section within that file; see the documentation of the
73 individual command for details.
74 .PP
75 This page uses \fBextensions\fR as the name of the section, when needed
76 in examples.
77 .PP
78 Each entry in the extension section takes the form:
79 .PP
80 .Vb 1
81 \& name = [critical, ]value(s)
82 .Ve
83 .PP
84 If \fBcritical\fR is present then the extension will be marked as critical.
85 .PP
86 If multiple entries are processed for the same extension name,
87 later entries override earlier ones with the same name.
88 .PP
89 The format of \fBvalues\fR depends on the value of \fBname\fR, many have a
90 type-value pairing where the type and value are separated by a colon.
91 There are four main types of extension:
92 .PP
93 .Vb 4
94 \& string
95 \& multi\-valued
96 \& raw
97 \& arbitrary
98 .Ve
99 .PP
100 Each is described in the following paragraphs.
101 .PP
102 String extensions simply have a string which contains either the value itself
103 or how it is obtained.
104 .PP
105 Multi-valued extensions have a short form and a long form. The short form
106 is a comma-separated list of names and values:
107 .PP
108 .Vb 1
109 \& basicConstraints = critical, CA:true, pathlen:1
110 .Ve
111 .PP
112 The long form allows the values to be placed in a separate section:
113 .PP
114 .Vb 2
115 \& [extensions]
116 \& basicConstraints = critical, @basic_constraints
117 \&
118 \& [basic_constraints]
119 \& CA = true
120 \& pathlen = 1
121 .Ve
122 .PP
123 Both forms are equivalent.
124 .PP
125 If an extension is multi-value and a field value must contain a comma the long
126 form must be used otherwise the comma would be misinterpreted as a field
127 separator. For example:
128 .PP
129 .Vb 1
130 \& subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
131 .Ve
132 .PP
133 will produce an error but the equivalent form:
134 .PP
135 .Vb 2
136 \& [extensions]
137 \& subjectAltName = @subject_alt_section
138 \&
139 \& [subject_alt_section]
140 \& subjectAltName = URI:ldap://somehost.com/CN=foo,OU=bar
141 .Ve
142 .PP
143 is valid.
144 .PP
145 OpenSSL does not support multiple occurrences of the same field within a
146 section. In this example:
147 .PP
148 .Vb 2
149 \& [extensions]
150 \& subjectAltName = @alt_section
151 \&
152 \& [alt_section]
153 \& email = [email protected]
154 \& email = [email protected]
155 .Ve
156 .PP
157 will only recognize the last value. To specify multiple values append a
158 numeric identifier, as shown here:
159 .PP
160 .Vb 2
161 \& [extensions]
162 \& subjectAltName = @alt_section
163 \&
164 \& [alt_section]
165 \& email.1 = [email protected]
166 \& email.2 = [email protected]
167 .Ve
168 .PP
169 The syntax of raw extensions is defined by the source code that parses
170 the extension but should be documented.
171 See "Certificate Policies" for an example of a raw extension.
172 .PP
173 If an extension type is unsupported, then the \fIarbitrary\fR extension syntax
174 must be used, see the "ARBITRARY EXTENSIONS" section for more details.
175 .SH "STANDARD EXTENSIONS"
176 .IX Header "STANDARD EXTENSIONS"
177 The following sections describe the syntax of each supported extension.
178 They do not define the semantics of the extension.
179 .SS "Basic Constraints"
180 .IX Subsection "Basic Constraints"
181 This is a multi-valued extension which indicates whether a certificate is
182 a CA certificate. The first value is \fBCA\fR followed by \fBTRUE\fR or
183 \&\fBFALSE\fR. If \fBCA\fR is \fBTRUE\fR then an optional \fBpathlen\fR name followed by a
184 nonnegative value can be included.
185 .PP
186 For example:
187 .PP
188 .Vb 1
189 \& basicConstraints = CA:TRUE
190 \&
191 \& basicConstraints = CA:FALSE
192 \&
193 \& basicConstraints = critical, CA:TRUE, pathlen:1
194 .Ve
195 .PP
196 A CA certificate \fImust\fR include the \fBbasicConstraints\fR name with the \fBCA\fR
197 parameter set to \fBTRUE\fR. An end-user certificate must either have \fBCA:FALSE\fR
198 or omit the extension entirely.
199 The \fBpathlen\fR parameter specifies the maximum number of CAs that can appear
200 below this one in a chain. A \fBpathlen\fR of zero means the CA cannot sign
201 any sub-CA's, and can only sign end-entity certificates.
202 .SS "Key Usage"
203 .IX Subsection "Key Usage"
204 Key usage is a multi-valued extension consisting of a list of names of
205 the permitted key usages. The defined values are: \f(CW\*(C`digitalSignature\*(C'\fR,
206 \&\f(CW\*(C`nonRepudiation\*(C'\fR (with an alternative name \f(CW\*(C`contentCommitment\*(C'\fR),
207 \&\f(CW\*(C`keyEncipherment\*(C'\fR, \f(CW\*(C`dataEncipherment\*(C'\fR, \f(CW\*(C`keyAgreement\*(C'\fR, \f(CW\*(C`keyCertSign\*(C'\fR,
208 \&\f(CW\*(C`cRLSign\*(C'\fR, \f(CW\*(C`encipherOnly\*(C'\fR, and \f(CW\*(C`decipherOnly\*(C'\fR.
209 .PP
210 Examples:
211 .PP
212 .Vb 1
213 \& keyUsage = digitalSignature, nonRepudiation
214 \&
215 \& keyUsage = digitalSignature, contentCommitment
216 \&
217 \& keyUsage = critical, keyCertSign
218 .Ve
219 .SS "Extended Key Usage"
220 .IX Subsection "Extended Key Usage"
221 This extension consists of a list of values indicating purposes for which
222 the certificate public key can be used.
223 Each value can be either a short text name or an OID.
224 The following text names, and their intended meaning, are known:
225 .PP
226 .Vb 10
227 \& Value Meaning according to RFC 5280 etc.
228 \& \-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-
229 \& serverAuth SSL/TLS WWW Server Authentication
230 \& clientAuth SSL/TLS WWW Client Authentication
231 \& codeSigning Code Signing
232 \& emailProtection E\-mail Protection (S/MIME)
233 \& timeStamping Trusted Timestamping
234 \& OCSPSigning OCSP Signing
235 \& ipsecIKE ipsec Internet Key Exchange
236 \& msCodeInd Microsoft Individual Code Signing (authenticode)
237 \& msCodeCom Microsoft Commercial Code Signing (authenticode)
238 \& msCTLSign Microsoft Trust List Signing
239 \& msEFS Microsoft Encrypted File System
240 .Ve
241 .PP
242 While IETF RFC 5280 says that \fBid-kp-serverAuth\fR and \fBid-kp-clientAuth\fR
243 are only for WWW use, in practice they are used for all kinds of TLS clients
244 and servers, and this is what OpenSSL assumes as well.
245 .PP
246 Examples:
247 .PP
248 .Vb 1
249 \& extendedKeyUsage = critical, codeSigning, 1.2.3.4
250 \&
251 \& extendedKeyUsage = serverAuth, clientAuth
252 .Ve
253 .SS "Subject Key Identifier"
254 .IX Subsection "Subject Key Identifier"
255 The SKID extension specification has a value with three choices.
256 .IP \fBnone\fR 4
257 .IX Item "none"
258 No SKID extension will be included.
259 .IP \fBhash\fR 4
260 .IX Item "hash"
261 The process specified in RFC 5280 section 4.2.1.2. (1) is followed:
262 The keyIdentifier is composed of the 160\-bit SHA\-1 hash of the value of the BIT
263 STRING subjectPublicKey (excluding the tag, length, and number of unused bits).
264 .ie n .IP "A hex string (possibly with "":"" separating bytes)" 4
265 .el .IP "A hex string (possibly with \f(CW:\fR separating bytes)" 4
266 .IX Item "A hex string (possibly with : separating bytes)"
267 The provided value is output directly.
268 This choice is strongly discouraged.
269 .PP
270 By default the \fBx509\fR, \fBreq\fR, and \fBca\fR apps behave as if \fBhash\fR was given.
271 .PP
272 Example:
273 .PP
274 .Vb 1
275 \& subjectKeyIdentifier = hash
276 .Ve
277 .SS "Authority Key Identifier"
278 .IX Subsection "Authority Key Identifier"
279 The AKID extension specification may have the value \fBnone\fR
280 indicating that no AKID shall be included.
281 Otherwise it may have the value \fBkeyid\fR or \fBissuer\fR
282 or both of them, separated by \f(CW\*(C`,\*(C'\fR.
283 Either or both can have the option \fBalways\fR,
284 indicated by putting a colon \f(CW\*(C`:\*(C'\fR between the value and this option.
285 For self-signed certificates the AKID is suppressed unless \fBalways\fR is present.
286 .PP
287 By default the \fBx509\fR, \fBreq\fR, and \fBca\fR apps behave as if \fBnone\fR was given
288 for self-signed certificates and \fBkeyid\fR\f(CW\*(C`,\*(C'\fR \fBissuer\fR otherwise.
289 .PP
290 If \fBkeyid\fR is present, an attempt is made to
291 copy the subject key identifier (SKID) from the issuer certificate except if
292 the issuer certificate is the same as the current one and it is not self-signed.
293 The hash of the public key related to the signing key is taken as fallback
294 if the issuer certificate is the same as the current certificate.
295 If \fBalways\fR is present but no value can be obtained, an error is returned.
296 .PP
297 If \fBissuer\fR is present, and in addition it has the option \fBalways\fR specified
298 or \fBkeyid\fR is not present,
299 then the issuer DN and serial number are copied from the issuer certificate.
300 If this fails, an error is returned.
301 .PP
302 Examples:
303 .PP
304 .Vb 1
305 \& authorityKeyIdentifier = keyid, issuer
306 \&
307 \& authorityKeyIdentifier = keyid, issuer:always
308 .Ve
309 .SS "Subject Alternative Name"
310 .IX Subsection "Subject Alternative Name"
311 This is a multi-valued extension that supports several types of name
312 identifier, including
313 \&\fBemail\fR (an email address),
314 \&\fBURI\fR (a uniform resource indicator),
315 \&\fBDNS\fR (a DNS domain name),
316 \&\fBRID\fR (a registered ID: OBJECT IDENTIFIER),
317 \&\fBIP\fR (an IP address),
318 \&\fBdirName\fR (a distinguished name),
319 and \fBotherName\fR.
320 The syntax of each is described in the following paragraphs.
321 .PP
322 The \fBemail\fR option has two special values.
323 \&\f(CW\*(C`copy\*(C'\fR will automatically include any email addresses
324 contained in the certificate subject name in the extension.
325 \&\f(CW\*(C`move\*(C'\fR will automatically move any email addresses
326 from the certificate subject name to the extension.
327 .PP
328 The IP address used in the \fBIP\fR option can be in either IPv4 or IPv6 format.
329 .PP
330 The value of \fBdirName\fR is specifies the configuration section containing
331 the distinguished name to use, as a set of name-value pairs.
332 Multi-valued AVAs can be formed by prefacing the name with a \fB+\fR character.
333 .PP
334 The value of \fBotherName\fR can include arbitrary data associated with an OID;
335 the value should be the OID followed by a semicolon and the content in specified
336 using the syntax in \fBASN1_generate_nconf\fR\|(3).
337 .PP
338 Examples:
339 .PP
340 .Vb 1
341 \& subjectAltName = email:copy, email:[email protected], URI:http://my.example.com/
342 \&
343 \& subjectAltName = IP:192.168.7.1
344 \&
345 \& subjectAltName = IP:13::17
346 \&
347 \& subjectAltName = email:[email protected], RID:1.2.3.4
348 \&
349 \& subjectAltName = otherName:1.2.3.4;UTF8:some other identifier
350 \&
351 \& [extensions]
352 \& subjectAltName = dirName:dir_sect
353 \&
354 \& [dir_sect]
355 \& C = UK
356 \& O = My Organization
357 \& OU = My Unit
358 \& CN = My Name
359 .Ve
360 .PP
361 Non-ASCII Email Address conforming the syntax defined in Section 3.3 of RFC 6531
362 are provided as otherName.SmtpUTF8Mailbox. According to RFC 8398, the email
363 address should be provided as UTF8String. To enforce the valid representation in
364 the certificate, the SmtpUTF8Mailbox should be provided as follows
365 .PP
366 .Vb 3
367 \& subjectAltName=@alts
368 \& [alts]
369 \& otherName = 1.3.6.1.5.5.7.8.9;FORMAT:UTF8,UTF8String:nonasciiname.example.com
370 .Ve
371 .SS "Issuer Alternative Name"
372 .IX Subsection "Issuer Alternative Name"
373 This extension supports most of the options of subject alternative name;
374 it does not support \fBemail:copy\fR.
375 It also adds \fBissuer:copy\fR as an allowed value, which copies any subject
376 alternative names from the issuer certificate, if possible.
377 .PP
378 Example:
379 .PP
380 .Vb 1
381 \& issuerAltName = issuer:copy
382 .Ve
383 .SS "Authority Info Access"
384 .IX Subsection "Authority Info Access"
385 This extension gives details about how to retrieve information that
386 related to the certificate that the CA makes available. The syntax is
387 \&\fBaccess_id;location\fR, where \fBaccess_id\fR is an object identifier
388 (although only a few values are well-known) and \fBlocation\fR has the same
389 syntax as subject alternative name (except that \fBemail:copy\fR is not supported).
390 .PP
391 Possible values for access_id include \fBOCSP\fR (OCSP responder),
392 \&\fBcaIssuers\fR (CA Issuers),
393 \&\fBad_timestamping\fR (AD Time Stamping),
394 \&\fBAD_DVCS\fR (ad dvcs),
395 \&\fBcaRepository\fR (CA Repository).
396 .PP
397 Examples:
398 .PP
399 .Vb 1
400 \& authorityInfoAccess = OCSP;URI:http://ocsp.example.com/,caIssuers;URI:http://myca.example.com/ca.cer
401 \&
402 \& authorityInfoAccess = OCSP;URI:http://ocsp.example.com/
403 .Ve
404 .SS "CRL distribution points"
405 .IX Subsection "CRL distribution points"
406 This is a multi-valued extension whose values can be either a name-value
407 pair using the same form as subject alternative name or a single value
408 specifying the section name containing all the distribution point values.
409 .PP
410 When a name-value pair is used, a DistributionPoint extension will
411 be set with the given value as the fullName field as the distributionPoint
412 value, and the reasons and cRLIssuer fields will be omitted.
413 .PP
414 When a single option is used, the value specifies the section, and that
415 section can have the following items:
416 .IP fullname 4
417 .IX Item "fullname"
418 The full name of the distribution point, in the same format as the subject
419 alternative name.
420 .IP relativename 4
421 .IX Item "relativename"
422 The value is taken as a distinguished name fragment that is set as the
423 value of the nameRelativeToCRLIssuer field.
424 .IP CRLIssuer 4
425 .IX Item "CRLIssuer"
426 The value must in the same format as the subject alternative name.
427 .IP reasons 4
428 .IX Item "reasons"
429 A multi-value field that contains the reasons for revocation. The recognized
430 values are: \f(CW\*(C`keyCompromise\*(C'\fR, \f(CW\*(C`CACompromise\*(C'\fR, \f(CW\*(C`affiliationChanged\*(C'\fR,
431 \&\f(CW\*(C`superseded\*(C'\fR, \f(CW\*(C`cessationOfOperation\*(C'\fR, \f(CW\*(C`certificateHold\*(C'\fR,
432 \&\f(CW\*(C`privilegeWithdrawn\*(C'\fR, and \f(CW\*(C`AACompromise\*(C'\fR.
433 .PP
434 Only one of \fBfullname\fR or \fBrelativename\fR should be specified.
435 .PP
436 Simple examples:
437 .PP
438 .Vb 1
439 \& crlDistributionPoints = URI:http://example.com/myca.crl
440 \&
441 \& crlDistributionPoints = URI:http://example.com/myca.crl, URI:http://example.org/my.crl
442 .Ve
443 .PP
444 Full distribution point example:
445 .PP
446 .Vb 2
447 \& [extensions]
448 \& crlDistributionPoints = crldp1_section
449 \&
450 \& [crldp1_section]
451 \& fullname = URI:http://example.com/myca.crl
452 \& CRLissuer = dirName:issuer_sect
453 \& reasons = keyCompromise, CACompromise
454 \&
455 \& [issuer_sect]
456 \& C = UK
457 \& O = Organisation
458 \& CN = Some Name
459 .Ve
460 .SS "Issuing Distribution Point"
461 .IX Subsection "Issuing Distribution Point"
462 This extension should only appear in CRLs. It is a multi-valued extension
463 whose syntax is similar to the "section" pointed to by the CRL distribution
464 points extension. The following names have meaning:
465 .IP fullname 4
466 .IX Item "fullname"
467 The full name of the distribution point, in the same format as the subject
468 alternative name.
469 .IP relativename 4
470 .IX Item "relativename"
471 The value is taken as a distinguished name fragment that is set as the
472 value of the nameRelativeToCRLIssuer field.
473 .IP onlysomereasons 4
474 .IX Item "onlysomereasons"
475 A multi-value field that contains the reasons for revocation. The recognized
476 values are: \f(CW\*(C`keyCompromise\*(C'\fR, \f(CW\*(C`CACompromise\*(C'\fR, \f(CW\*(C`affiliationChanged\*(C'\fR,
477 \&\f(CW\*(C`superseded\*(C'\fR, \f(CW\*(C`cessationOfOperation\*(C'\fR, \f(CW\*(C`certificateHold\*(C'\fR,
478 \&\f(CW\*(C`privilegeWithdrawn\*(C'\fR, and \f(CW\*(C`AACompromise\*(C'\fR.
479 .IP "onlyuser, onlyCA, onlyAA, indirectCRL" 4
480 .IX Item "onlyuser, onlyCA, onlyAA, indirectCRL"
481 The value for each of these names is a boolean.
482 .PP
483 Example:
484 .PP
485 .Vb 2
486 \& [extensions]
487 \& issuingDistributionPoint = critical, @idp_section
488 \&
489 \& [idp_section]
490 \& fullname = URI:http://example.com/myca.crl
491 \& indirectCRL = TRUE
492 \& onlysomereasons = keyCompromise, CACompromise
493 .Ve
494 .SS "Certificate Policies"
495 .IX Subsection "Certificate Policies"
496 This is a \fIraw\fR extension that supports all of the defined fields of the
497 certificate extension.
498 .PP
499 Policies without qualifiers are specified by giving the OID.
500 Multiple policies are comma-separated. For example:
501 .PP
502 .Vb 1
503 \& certificatePolicies = 1.2.4.5, 1.1.3.4
504 .Ve
505 .PP
506 To include policy qualifiers, use the "@section" syntax to point to a
507 section that specifies all the information.
508 .PP
509 The section referred to must include the policy OID using the name
510 \&\fBpolicyIdentifier\fR. cPSuri qualifiers can be included using the syntax:
511 .PP
512 .Vb 1
513 \& CPS.nnn = value
514 .Ve
515 .PP
516 where \f(CW\*(C`nnn\*(C'\fR is a number.
517 .PP
518 userNotice qualifiers can be set using the syntax:
519 .PP
520 .Vb 1
521 \& userNotice.nnn = @notice
522 .Ve
523 .PP
524 The value of the userNotice qualifier is specified in the relevant section.
525 This section can include \fBexplicitText\fR, \fBorganization\fR, and \fBnoticeNumbers\fR
526 options. explicitText and organization are text strings, noticeNumbers is a
527 comma separated list of numbers. The organization and noticeNumbers options
528 (if included) must BOTH be present. Some software might require
529 the \fBia5org\fR option at the top level; this changes the encoding from
530 Displaytext to IA5String.
531 .PP
532 Example:
533 .PP
534 .Vb 2
535 \& [extensions]
536 \& certificatePolicies = ia5org, 1.2.3.4, 1.5.6.7.8, @polsect
537 \&
538 \& [polsect]
539 \& policyIdentifier = 1.3.5.8
540 \& CPS.1 = "http://my.host.example.com/"
541 \& CPS.2 = "http://my.your.example.com/"
542 \& userNotice.1 = @notice
543 \&
544 \& [notice]
545 \& explicitText = "Explicit Text Here"
546 \& organization = "Organisation Name"
547 \& noticeNumbers = 1, 2, 3, 4
548 .Ve
549 .PP
550 The character encoding of explicitText can be specified by prefixing the
551 value with \fBUTF8\fR, \fBBMP\fR, or \fBVISIBLE\fR followed by colon. For example:
552 .PP
553 .Vb 2
554 \& [notice]
555 \& explicitText = "UTF8:Explicit Text Here"
556 .Ve
557 .SS "Policy Constraints"
558 .IX Subsection "Policy Constraints"
559 This is a multi-valued extension which consisting of the names
560 \&\fBrequireExplicitPolicy\fR or \fBinhibitPolicyMapping\fR and a non negative integer
561 value. At least one component must be present.
562 .PP
563 Example:
564 .PP
565 .Vb 1
566 \& policyConstraints = requireExplicitPolicy:3
567 .Ve
568 .SS "Inhibit Any Policy"
569 .IX Subsection "Inhibit Any Policy"
570 This is a string extension whose value must be a non negative integer.
571 .PP
572 Example:
573 .PP
574 .Vb 1
575 \& inhibitAnyPolicy = 2
576 .Ve
577 .SS "Name Constraints"
578 .IX Subsection "Name Constraints"
579 This is a multi-valued extension. The name should
580 begin with the word \fBpermitted\fR or \fBexcluded\fR followed by a \fB;\fR. The rest of
581 the name and the value follows the syntax of subjectAltName except
582 \&\fBemail:copy\fR
583 is not supported and the \fBIP\fR form should consist of an IP addresses and
584 subnet mask separated by a \fB/\fR.
585 .PP
586 Examples:
587 .PP
588 .Vb 1
589 \& nameConstraints = permitted;IP:192.168.0.0/255.255.0.0
590 \&
591 \& nameConstraints = permitted;email:.example.com
592 \&
593 \& nameConstraints = excluded;email:.com
594 .Ve
595 .SS "OCSP No Check"
596 .IX Subsection "OCSP No Check"
597 This is a string extension. It is parsed, but ignored.
598 .PP
599 Example:
600 .PP
601 .Vb 1
602 \& noCheck = ignored
603 .Ve
604 .SS "TLS Feature (aka Must Staple)"
605 .IX Subsection "TLS Feature (aka Must Staple)"
606 This is a multi-valued extension consisting of a list of TLS extension
607 identifiers. Each identifier may be a number (0..65535) or a supported name.
608 When a TLS client sends a listed extension, the TLS server is expected to
609 include that extension in its reply.
610 .PP
611 The supported names are: \fBstatus_request\fR and \fBstatus_request_v2\fR.
612 .PP
613 Example:
614 .PP
615 .Vb 1
616 \& tlsfeature = status_request
617 .Ve
618 .SH "DEPRECATED EXTENSIONS"
619 .IX Header "DEPRECATED EXTENSIONS"
620 The following extensions are non standard, Netscape specific and largely
621 obsolete. Their use in new applications is discouraged.
622 .SS "Netscape String extensions"
623 .IX Subsection "Netscape String extensions"
624 Netscape Comment (\fBnsComment\fR) is a string extension containing a comment
625 which will be displayed when the certificate is viewed in some browsers.
626 Other extensions of this type are: \fBnsBaseUrl\fR,
627 \&\fBnsRevocationUrl\fR, \fBnsCaRevocationUrl\fR, \fBnsRenewalUrl\fR, \fBnsCaPolicyUrl\fR
628 and \fBnsSslServerName\fR.
629 .SS "Netscape Certificate Type"
630 .IX Subsection "Netscape Certificate Type"
631 This is a multi-valued extensions which consists of a list of flags to be
632 included. It was used to indicate the purposes for which a certificate could
633 be used. The basicConstraints, keyUsage and extended key usage extensions are
634 now used instead.
635 .PP
636 Acceptable values for nsCertType are: \fBclient\fR, \fBserver\fR, \fBemail\fR,
637 \&\fBobjsign\fR, \fBreserved\fR, \fBsslCA\fR, \fBemailCA\fR, \fBobjCA\fR.
638 .SH "ARBITRARY EXTENSIONS"
639 .IX Header "ARBITRARY EXTENSIONS"
640 If an extension is not supported by the OpenSSL code then it must be encoded
641 using the arbitrary extension format. It is also possible to use the arbitrary
642 format for supported extensions. Extreme care should be taken to ensure that
643 the data is formatted correctly for the given extension type.
644 .PP
645 There are two ways to encode arbitrary extensions.
646 .PP
647 The first way is to use the word ASN1 followed by the extension content
648 using the same syntax as \fBASN1_generate_nconf\fR\|(3).
649 For example:
650 .PP
651 .Vb 3
652 \& [extensions]
653 \& 1.2.3.4 = critical, ASN1:UTF8String:Some random data
654 \& 1.2.3.4.1 = ASN1:SEQUENCE:seq_sect
655 \&
656 \& [seq_sect]
657 \& field1 = UTF8:field1
658 \& field2 = UTF8:field2
659 .Ve
660 .PP
661 It is also possible to use the word DER to include the raw encoded data in any
662 extension.
663 .PP
664 .Vb 2
665 \& 1.2.3.4 = critical, DER:01:02:03:04
666 \& 1.2.3.4.1 = DER:01020304
667 .Ve
668 .PP
669 The value following DER is a hex dump of the DER encoding of the extension
670 Any extension can be placed in this form to override the default behaviour.
671 For example:
672 .PP
673 .Vb 1
674 \& basicConstraints = critical, DER:00:01:02:03
675 .Ve
676 .SH WARNINGS
677 .IX Header "WARNINGS"
678 There is no guarantee that a specific implementation will process a given
679 extension. It may therefore be sometimes possible to use certificates for
680 purposes prohibited by their extensions because a specific application does
681 not recognize or honour the values of the relevant extensions.
682 .PP
683 The DER and ASN1 options should be used with caution. It is possible to create
684 invalid extensions if they are not used carefully.
685 .SH "SEE ALSO"
686 .IX Header "SEE ALSO"
687 \&\fBopenssl\-req\fR\|(1), \fBopenssl\-ca\fR\|(1), \fBopenssl\-x509\fR\|(1),
688 \&\fBASN1_generate_nconf\fR\|(3)
689 .SH COPYRIGHT
690 .IX Header "COPYRIGHT"
691 Copyright 2004\-2025 The OpenSSL Project Authors. All Rights Reserved.
692 .PP
693 Licensed under the Apache License 2.0 (the "License"). You may not use
694 this file except in compliance with the License. You can obtain a copy
695 in the file LICENSE in the source distribution or at
696 <https://www.openssl.org/source/license.html>.