1=pod 2 3=for comment openssl_manual_section:5 4 5=head1 NAME 6 7x509v3_config - X509 V3 certificate extension configuration format 8 9=head1 DESCRIPTION 10 11Several of the OpenSSL utilities can add extensions to a certificate or 12certificate request based on the contents of a configuration file. 13 14Typically the application will contain an option to point to an extension 15section. Each line of the extension section takes the form: 16 17 extension_name=[critical,] extension_options 18 19If B<critical> is present then the extension will be critical. 20 21The format of B<extension_options> depends on the value of B<extension_name>. 22 23There are four main types of extension: I<string> extensions, I<multi-valued> 24extensions, I<raw> and I<arbitrary> extensions. 25 26String extensions simply have a string which contains either the value itself 27or how it is obtained. 28 29For example: 30 31 nsComment="This is a Comment" 32 33Multi-valued extensions have a short form and a long form. The short form 34is a list of names and values: 35 36 basicConstraints=critical,CA:true,pathlen:1 37 38The long form allows the values to be placed in a separate section: 39 40 basicConstraints=critical,@bs_section 41 42 [bs_section] 43 44 CA=true 45 pathlen=1 46 47Both forms are equivalent. 48 49The syntax of raw extensions is governed by the extension code: it can 50for example contain data in multiple sections. The correct syntax to 51use is defined by the extension code itself: check out the certificate 52policies extension for an example. 53 54If an extension type is unsupported then the I<arbitrary> extension syntax 55must be used, see the L<ARBITRARY EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. 56 57=head1 STANDARD EXTENSIONS 58 59The following sections describe each supported extension in detail. 60 61=head2 Basic Constraints. 62 63This is a multi valued extension which indicates whether a certificate is 64a CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or 65B<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an 66non-negative value can be included. 67 68For example: 69 70 basicConstraints=CA:TRUE 71 72 basicConstraints=CA:FALSE 73 74 basicConstraints=critical,CA:TRUE, pathlen:0 75 76A CA certificate B<must> include the basicConstraints value with the CA field 77set to TRUE. An end user certificate must either set CA to FALSE or exclude the 78extension entirely. Some software may require the inclusion of basicConstraints 79with CA set to FALSE for end entity certificates. 80 81The pathlen parameter indicates the maximum number of CAs that can appear 82below this one in a chain. So if you have a CA with a pathlen of zero it can 83only be used to sign end user certificates and not further CAs. 84 85 86=head2 Key Usage. 87 88Key usage is a multi valued extension consisting of a list of names of the 89permitted key usages. 90 91The supporte names are: digitalSignature, nonRepudiation, keyEncipherment, 92dataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly 93and decipherOnly. 94 95Examples: 96 97 keyUsage=digitalSignature, nonRepudiation 98 99 keyUsage=critical, keyCertSign 100 101 102=head2 Extended Key Usage. 103 104This extensions consists of a list of usages indicating purposes for which 105the certificate public key can be used for, 106 107These can either be object short names of the dotted numerical form of OIDs. 108While any OID can be used only certain values make sense. In particular the 109following PKIX, NS and MS values are meaningful: 110 111 Value Meaning 112 ----- ------- 113 serverAuth SSL/TLS Web Server Authentication. 114 clientAuth SSL/TLS Web Client Authentication. 115 codeSigning Code signing. 116 emailProtection E-mail Protection (S/MIME). 117 timeStamping Trusted Timestamping 118 msCodeInd Microsoft Individual Code Signing (authenticode) 119 msCodeCom Microsoft Commercial Code Signing (authenticode) 120 msCTLSign Microsoft Trust List Signing 121 msSGC Microsoft Server Gated Crypto 122 msEFS Microsoft Encrypted File System 123 nsSGC Netscape Server Gated Crypto 124 125Examples: 126 127 extendedKeyUsage=critical,codeSigning,1.2.3.4 128 extendedKeyUsage=nsSGC,msSGC 129 130 131=head2 Subject Key Identifier. 132 133This is really a string extension and can take two possible values. Either 134the word B<hash> which will automatically follow the guidelines in RFC3280 135or a hex string giving the extension value to include. The use of the hex 136string is strongly discouraged. 137 138Example: 139 140 subjectKeyIdentifier=hash 141 142 143=head2 Authority Key Identifier. 144 145The authority key identifier extension permits two options. keyid and issuer: 146both can take the optional value "always". 147 148If the keyid option is present an attempt is made to copy the subject key 149identifier from the parent certificate. If the value "always" is present 150then an error is returned if the option fails. 151 152The issuer option copies the issuer and serial number from the issuer 153certificate. This will only be done if the keyid option fails or 154is not included unless the "always" flag will always include the value. 155 156Example: 157 158 authorityKeyIdentifier=keyid,issuer 159 160 161=head2 Subject Alternative Name. 162 163The subject alternative name extension allows various literal values to be 164included in the configuration file. These include B<email> (an email address) 165B<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a 166registered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName> 167(a distinguished name) and otherName. 168 169The email option include a special 'copy' value. This will automatically 170include and email addresses contained in the certificate subject name in 171the extension. 172 173The IP address used in the B<IP> options can be in either IPv4 or IPv6 format. 174 175The value of B<dirName> should point to a section containing the distinguished 176name to use as a set of name value pairs. Multi values AVAs can be formed by 177prefacing the name with a B<+> character. 178 179otherName can include arbitrary data associated with an OID: the value 180should be the OID followed by a semicolon and the content in standard 181L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> format. 182 183Examples: 184 185 subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ 186 subjectAltName=IP:192.168.7.1 187 subjectAltName=IP:13::17 188 subjectAltName=email:my@other.address,RID:1.2.3.4 189 subjectAltName=otherName:1.2.3.4;UTF8:some other identifier 190 191 subjectAltName=dirName:dir_sect 192 193 [dir_sect] 194 C=UK 195 O=My Organization 196 OU=My Unit 197 CN=My Name 198 199 200=head2 Issuer Alternative Name. 201 202The issuer alternative name option supports all the literal options of 203subject alternative name. It does B<not> support the email:copy option because 204that would not make sense. It does support an additional issuer:copy option 205that will copy all the subject alternative name values from the issuer 206certificate (if possible). 207 208Example: 209 210 issuserAltName = issuer:copy 211 212 213=head2 Authority Info Access. 214 215The authority information access extension gives details about how to access 216certain information relating to the CA. Its syntax is accessOID;location 217where I<location> has the same syntax as subject alternative name (except 218that email:copy is not supported). accessOID can be any valid OID but only 219certain values are meaningful, for example OCSP and caIssuers. 220 221Example: 222 223 authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ 224 authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html 225 226 227=head2 CRL distribution points. 228 229This is a multi-valued extension whose options can be either in name:value pair 230using the same form as subject alternative name or a single value representing 231a section name containing all the distribution point fields. 232 233For a name:value pair a new DistributionPoint with the fullName field set to 234the given value both the cRLissuer and reasons fields are omitted in this case. 235 236In the single option case the section indicated contains values for each 237field. In this section: 238 239If the name is "fullname" the value field should contain the full name 240of the distribution point in the same format as subject alternative name. 241 242If the name is "relativename" then the value field should contain a section 243name whose contents represent a DN fragment to be placed in this field. 244 245The name "CRLIssuer" if present should contain a value for this field in 246subject alternative name format. 247 248If the name is "reasons" the value field should consist of a comma 249separated field containing the reasons. Valid reasons are: "keyCompromise", 250"CACompromise", "affiliationChanged", "superseded", "cessationOfOperation", 251"certificateHold", "privilegeWithdrawn" and "AACompromise". 252 253 254Simple examples: 255 256 crlDistributionPoints=URI:http://myhost.com/myca.crl 257 crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl 258 259Full distribution point example: 260 261 crlDistributionPoints=crldp1_section 262 263 [crldp1_section] 264 265 fullname=URI:http://myhost.com/myca.crl 266 CRLissuer=dirName:issuer_sect 267 reasons=keyCompromise, CACompromise 268 269 [issuer_sect] 270 C=UK 271 O=Organisation 272 CN=Some Name 273 274=head2 Issuing Distribution Point 275 276This extension should only appear in CRLs. It is a multi valued extension 277whose syntax is similar to the "section" pointed to by the CRL distribution 278points extension with a few differences. 279 280The names "reasons" and "CRLissuer" are not recognized. 281 282The name "onlysomereasons" is accepted which sets this field. The value is 283in the same format as the CRL distribution point "reasons" field. 284 285The names "onlyuser", "onlyCA", "onlyAA" and "indirectCRL" are also accepted 286the values should be a boolean value (TRUE or FALSE) to indicate the value of 287the corresponding field. 288 289Example: 290 291 issuingDistributionPoint=critical, @idp_section 292 293 [idp_section] 294 295 fullname=URI:http://myhost.com/myca.crl 296 indirectCRL=TRUE 297 onlysomereasons=keyCompromise, CACompromise 298 299 [issuer_sect] 300 C=UK 301 O=Organisation 302 CN=Some Name 303 304 305=head2 Certificate Policies. 306 307This is a I<raw> extension. All the fields of this extension can be set by 308using the appropriate syntax. 309 310If you follow the PKIX recommendations and just using one OID then you just 311include the value of that OID. Multiple OIDs can be set separated by commas, 312for example: 313 314 certificatePolicies= 1.2.4.5, 1.1.3.4 315 316If you wish to include qualifiers then the policy OID and qualifiers need to 317be specified in a separate section: this is done by using the @section syntax 318instead of a literal OID value. 319 320The section referred to must include the policy OID using the name 321policyIdentifier, cPSuri qualifiers can be included using the syntax: 322 323 CPS.nnn=value 324 325userNotice qualifiers can be set using the syntax: 326 327 userNotice.nnn=@notice 328 329The value of the userNotice qualifier is specified in the relevant section. 330This section can include explicitText, organization and noticeNumbers 331options. explicitText and organization are text strings, noticeNumbers is a 332comma separated list of numbers. The organization and noticeNumbers options 333(if included) must BOTH be present. If you use the userNotice option with IE5 334then you need the 'ia5org' option at the top level to modify the encoding: 335otherwise it will not be interpreted properly. 336 337Example: 338 339 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect 340 341 [polsect] 342 343 policyIdentifier = 1.3.5.8 344 CPS.1="http://my.host.name/" 345 CPS.2="http://my.your.name/" 346 userNotice.1=@notice 347 348 [notice] 349 350 explicitText="Explicit Text Here" 351 organization="Organisation Name" 352 noticeNumbers=1,2,3,4 353 354The B<ia5org> option changes the type of the I<organization> field. In RFC2459 355it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible. 356Some software (for example some versions of MSIE) may require ia5org. 357 358=head2 Policy Constraints 359 360This is a multi-valued extension which consisting of the names 361B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger 362value. At least one component must be present. 363 364Example: 365 366 policyConstraints = requireExplicitPolicy:3 367 368 369=head2 Inhibit Any Policy 370 371This is a string extension whose value must be a non negative integer. 372 373Example: 374 375 inhibitAnyPolicy = 2 376 377 378=head2 Name Constraints 379 380The name constraints extension is a multi-valued extension. The name should 381begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of 382the name and the value follows the syntax of subjectAltName except email:copy 383is not supported and the B<IP> form should consist of an IP addresses and 384subnet mask separated by a B</>. 385 386Examples: 387 388 nameConstraints=permitted;IP:192.168.0.0/255.255.0.0 389 390 nameConstraints=permitted;email:.somedomain.com 391 392 nameConstraints=excluded;email:.com 393 394 395=head2 OCSP No Check 396 397The OCSP No Check extension is a string extension but its value is ignored. 398 399Example: 400 401 noCheck = ignored 402 403 404=head1 DEPRECATED EXTENSIONS 405 406The following extensions are non standard, Netscape specific and largely 407obsolete. Their use in new applications is discouraged. 408 409=head2 Netscape String extensions. 410 411Netscape Comment (B<nsComment>) is a string extension containing a comment 412which will be displayed when the certificate is viewed in some browsers. 413 414Example: 415 416 nsComment = "Some Random Comment" 417 418Other supported extensions in this category are: B<nsBaseUrl>, 419B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> 420and B<nsSslServerName>. 421 422 423=head2 Netscape Certificate Type 424 425This is a multi-valued extensions which consists of a list of flags to be 426included. It was used to indicate the purposes for which a certificate could 427be used. The basicConstraints, keyUsage and extended key usage extensions are 428now used instead. 429 430Acceptable values for nsCertType are: B<client>, B<server>, B<email>, 431B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. 432 433 434=head1 ARBITRARY EXTENSIONS 435 436If an extension is not supported by the OpenSSL code then it must be encoded 437using the arbitrary extension format. It is also possible to use the arbitrary 438format for supported extensions. Extreme care should be taken to ensure that 439the data is formatted correctly for the given extension type. 440 441There are two ways to encode arbitrary extensions. 442 443The first way is to use the word ASN1 followed by the extension content 444using the same syntax as L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)>. 445For example: 446 447 1.2.3.4=critical,ASN1:UTF8String:Some random data 448 449 1.2.3.4=ASN1:SEQUENCE:seq_sect 450 451 [seq_sect] 452 453 field1 = UTF8:field1 454 field2 = UTF8:field2 455 456It is also possible to use the word DER to include the raw encoded data in any 457extension. 458 459 1.2.3.4=critical,DER:01:02:03:04 460 1.2.3.4=DER:01020304 461 462The value following DER is a hex dump of the DER encoding of the extension 463Any extension can be placed in this form to override the default behaviour. 464For example: 465 466 basicConstraints=critical,DER:00:01:02:03 467 468=head1 WARNING 469 470There is no guarantee that a specific implementation will process a given 471extension. It may therefore be sometimes possible to use certificates for 472purposes prohibited by their extensions because a specific application does 473not recognize or honour the values of the relevant extensions. 474 475The DER and ASN1 options should be used with caution. It is possible to create 476totally invalid extensions if they are not used carefully. 477 478 479=head1 NOTES 480 481If an extension is multi-value and a field value must contain a comma the long 482form must be used otherwise the comma would be misinterpreted as a field 483separator. For example: 484 485 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar 486 487will produce an error but the equivalent form: 488 489 subjectAltName=@subject_alt_section 490 491 [subject_alt_section] 492 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar 493 494is valid. 495 496Due to the behaviour of the OpenSSL B<conf> library the same field name 497can only occur once in a section. This means that: 498 499 subjectAltName=@alt_section 500 501 [alt_section] 502 503 email=steve@here 504 email=steve@there 505 506will only recognize the last value. This can be worked around by using the form: 507 508 [alt_section] 509 510 email.1=steve@here 511 email.2=steve@there 512 513=head1 HISTORY 514 515The X509v3 extension code was first added to OpenSSL 0.9.2. 516 517Policy mappings, inhibit any policy and name constraints support was added in 518OpenSSL 0.9.8 519 520The B<directoryName> and B<otherName> option as well as the B<ASN1> option 521for arbitrary extensions was added in OpenSSL 0.9.8 522 523=head1 SEE ALSO 524 525L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)>, 526L<ASN1_generate_nconf(3)|ASN1_generate_nconf(3)> 527 528 529=cut 530