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<ARBITRART 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 177preceeding 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 181ASN1_generate_nconf() 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 that supports all the literal options of 230subject alternative name. Of the few software packages that currently interpret 231this extension most only interpret the URI option. 232 233Currently each option will set a new DistributionPoint with the fullName 234field set to the given value. 235 236Other fields like cRLissuer and reasons cannot currently be set or displayed: 237at this time no examples were available that used these fields. 238 239Examples: 240 241 crlDistributionPoints=URI:http://myhost.com/myca.crl 242 crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl 243 244=head2 Certificate Policies. 245 246This is a I<raw> extension. All the fields of this extension can be set by 247using the appropriate syntax. 248 249If you follow the PKIX recommendations and just using one OID then you just 250include the value of that OID. Multiple OIDs can be set separated by commas, 251for example: 252 253 certificatePolicies= 1.2.4.5, 1.1.3.4 254 255If you wish to include qualifiers then the policy OID and qualifiers need to 256be specified in a separate section: this is done by using the @section syntax 257instead of a literal OID value. 258 259The section referred to must include the policy OID using the name 260policyIdentifier, cPSuri qualifiers can be included using the syntax: 261 262 CPS.nnn=value 263 264userNotice qualifiers can be set using the syntax: 265 266 userNotice.nnn=@notice 267 268The value of the userNotice qualifier is specified in the relevant section. 269This section can include explicitText, organization and noticeNumbers 270options. explicitText and organization are text strings, noticeNumbers is a 271comma separated list of numbers. The organization and noticeNumbers options 272(if included) must BOTH be present. If you use the userNotice option with IE5 273then you need the 'ia5org' option at the top level to modify the encoding: 274otherwise it will not be interpreted properly. 275 276Example: 277 278 certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect 279 280 [polsect] 281 282 policyIdentifier = 1.3.5.8 283 CPS.1="http://my.host.name/" 284 CPS.2="http://my.your.name/" 285 userNotice.1=@notice 286 287 [notice] 288 289 explicitText="Explicit Text Here" 290 organization="Organisation Name" 291 noticeNumbers=1,2,3,4 292 293The B<ia5org> option changes the type of the I<organization> field. In RFC2459 294it can only be of type DisplayText. In RFC3280 IA5Strring is also permissible. 295Some software (for example some versions of MSIE) may require ia5org. 296 297=head2 Policy Constraints 298 299This is a multi-valued extension which consisting of the names 300B<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger 301value. At least one component must be present. 302 303Example: 304 305 policyConstraints = requireExplicitPolicy:3 306 307 308=head2 Inhibit Any Policy 309 310This is a string extension whose value must be a non negative integer. 311 312Example: 313 314 inhibitAnyPolicy = 2 315 316 317=head2 Name Constraints 318 319The name constraints extension is a multi-valued extension. The name should 320begin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of 321the name and the value follows the syntax of subjectAltName except email:copy 322is not supported and the B<IP> form should consist of an IP addresses and 323subnet mask separated by a B</>. 324 325Examples: 326 327 nameConstraints=permitted;IP:192.168.0.0/255.255.0.0 328 329 nameConstraints=permitted;email:.somedomain.com 330 331 nameConstraints=excluded;email:.com 332 333=head1 DEPRECATED EXTENSIONS 334 335The following extensions are non standard, Netscape specific and largely 336obsolete. Their use in new applications is discouraged. 337 338=head2 Netscape String extensions. 339 340Netscape Comment (B<nsComment>) is a string extension containing a comment 341which will be displayed when the certificate is viewed in some browsers. 342 343Example: 344 345 nsComment = "Some Random Comment" 346 347Other supported extensions in this category are: B<nsBaseUrl>, 348B<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> 349and B<nsSslServerName>. 350 351 352=head2 Netscape Certificate Type 353 354This is a multi-valued extensions which consists of a list of flags to be 355included. It was used to indicate the purposes for which a certificate could 356be used. The basicConstraints, keyUsage and extended key usage extensions are 357now used instead. 358 359Acceptable values for nsCertType are: B<client>, B<server>, B<email>, 360B<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. 361 362 363=head1 ARBITRARY EXTENSIONS 364 365If an extension is not supported by the OpenSSL code then it must be encoded 366using the arbitrary extension format. It is also possible to use the arbitrary 367format for supported extensions. Extreme care should be taken to ensure that 368the data is formatted correctly for the given extension type. 369 370There are two ways to encode arbitrary extensions. 371 372The first way is to use the word ASN1 followed by the extension content 373using the same syntax as ASN1_generate_nconf(). For example: 374 375 1.2.3.4=critical,ASN1:UTF8String:Some random data 376 377 1.2.3.4=ASN1:SEQUENCE:seq_sect 378 379 [seq_sect] 380 381 field1 = UTF8:field1 382 field2 = UTF8:field2 383 384It is also possible to use the word DER to include the raw encoded data in any 385extension. 386 387 1.2.3.4=critical,DER:01:02:03:04 388 1.2.3.4=DER:01020304 389 390The value following DER is a hex dump of the DER encoding of the extension 391Any extension can be placed in this form to override the default behaviour. 392For example: 393 394 basicConstraints=critical,DER:00:01:02:03 395 396=head1 WARNING 397 398There is no guarantee that a specific implementation will process a given 399extension. It may therefore be sometimes possible to use certificates for 400purposes prohibited by their extensions because a specific application does 401not recognize or honour the values of the relevant extensions. 402 403The DER and ASN1 options should be used with caution. It is possible to create 404totally invalid extensions if they are not used carefully. 405 406 407=head1 NOTES 408 409If an extension is multi-value and a field value must contain a comma the long 410form must be used otherwise the comma would be misinterpreted as a field 411separator. For example: 412 413 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar 414 415will produce an error but the equivalent form: 416 417 subjectAltName=@subject_alt_section 418 419 [subject_alt_section] 420 subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar 421 422is valid. 423 424Due to the behaviour of the OpenSSL B<conf> library the same field name 425can only occur once in a section. This means that: 426 427 subjectAltName=@alt_section 428 429 [alt_section] 430 431 email=steve@here 432 email=steve@there 433 434will only recognize the last value. This can be worked around by using the form: 435 436 [alt_section] 437 438 email.1=steve@here 439 email.2=steve@there 440 441=head1 HISTORY 442 443The X509v3 extension code was first added to OpenSSL 0.9.2. 444 445Policy mappings, inhibit any policy and name constraints support was added in 446OpenSSL 0.9.8 447 448The B<directoryName> and B<otherName> option as well as the B<ASN1> option 449for arbitrary extensions was added in OpenSSL 0.9.8 450 451=head1 SEE ALSO 452 453L<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)> 454 455 456=cut 457