| 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>. |