x509v3_config.pod revision 160814
1160814Ssimon=pod 2160814Ssimon 3160814Ssimon=for comment openssl_manual_section:5 4160814Ssimon 5160814Ssimon=head1 NAME 6160814Ssimon 7160814Ssimonx509v3_config - X509 V3 certificate extension configuration format 8160814Ssimon 9160814Ssimon=head1 DESCRIPTION 10160814Ssimon 11160814SsimonSeveral of the OpenSSL utilities can add extensions to a certificate or 12160814Ssimoncertificate request based on the contents of a configuration file. 13160814Ssimon 14160814SsimonTypically the application will contain an option to point to an extension 15160814Ssimonsection. Each line of the extension section takes the form: 16160814Ssimon 17160814Ssimon extension_name=[critical,] extension_options 18160814Ssimon 19160814SsimonIf B<critical> is present then the extension will be critical. 20160814Ssimon 21160814SsimonThe format of B<extension_options> depends on the value of B<extension_name>. 22160814Ssimon 23160814SsimonThere are four main types of extension: I<string> extensions, I<multi-valued> 24160814Ssimonextensions, I<raw> and I<arbitrary> extensions. 25160814Ssimon 26160814SsimonString extensions simply have a string which contains either the value itself 27160814Ssimonor how it is obtained. 28160814Ssimon 29160814SsimonFor example: 30160814Ssimon 31160814Ssimon nsComment="This is a Comment" 32160814Ssimon 33160814SsimonMulti-valued extensions have a short form and a long form. The short form 34160814Ssimonis a list of names and values: 35160814Ssimon 36160814Ssimon basicConstraints=critical,CA:true,pathlen:1 37160814Ssimon 38160814SsimonThe long form allows the values to be placed in a separate section: 39160814Ssimon 40160814Ssimon basicConstraints=critical,@bs_section 41160814Ssimon 42160814Ssimon [bs_section] 43160814Ssimon 44160814Ssimon CA=true 45160814Ssimon pathlen=1 46160814Ssimon 47160814SsimonBoth forms are equivalent. 48160814Ssimon 49160814SsimonThe syntax of raw extensions is governed by the extension code: it can 50160814Ssimonfor example contain data in multiple sections. The correct syntax to 51160814Ssimonuse is defined by the extension code itself: check out the certificate 52160814Ssimonpolicies extension for an example. 53160814Ssimon 54160814SsimonIf an extension type is unsupported then the I<arbitrary> extension syntax 55160814Ssimonmust be used, see the L<ARBITRART EXTENSIONS|/"ARBITRARY EXTENSIONS"> section for more details. 56160814Ssimon 57160814Ssimon=head1 STANDARD EXTENSIONS 58160814Ssimon 59160814SsimonThe following sections describe each supported extension in detail. 60160814Ssimon 61160814Ssimon=head2 Basic Constraints. 62160814Ssimon 63160814SsimonThis is a multi valued extension which indicates whether a certificate is 64160814Ssimona CA certificate. The first (mandatory) name is B<CA> followed by B<TRUE> or 65160814SsimonB<FALSE>. If B<CA> is B<TRUE> then an optional B<pathlen> name followed by an 66160814Ssimonnon-negative value can be included. 67160814Ssimon 68160814SsimonFor example: 69160814Ssimon 70160814Ssimon basicConstraints=CA:TRUE 71160814Ssimon 72160814Ssimon basicConstraints=CA:FALSE 73160814Ssimon 74160814Ssimon basicConstraints=critical,CA:TRUE, pathlen:0 75160814Ssimon 76160814SsimonA CA certificate B<must> include the basicConstraints value with the CA field 77160814Ssimonset to TRUE. An end user certificate must either set CA to FALSE or exclude the 78160814Ssimonextension entirely. Some software may require the inclusion of basicConstraints 79160814Ssimonwith CA set to FALSE for end entity certificates. 80160814Ssimon 81160814SsimonThe pathlen parameter indicates the maximum number of CAs that can appear 82160814Ssimonbelow this one in a chain. So if you have a CA with a pathlen of zero it can 83160814Ssimononly be used to sign end user certificates and not further CAs. 84160814Ssimon 85160814Ssimon 86160814Ssimon=head2 Key Usage. 87160814Ssimon 88160814SsimonKey usage is a multi valued extension consisting of a list of names of the 89160814Ssimonpermitted key usages. 90160814Ssimon 91160814SsimonThe supporte names are: digitalSignature, nonRepudiation, keyEncipherment, 92160814SsimondataEncipherment, keyAgreement, keyCertSign, cRLSign, encipherOnly 93160814Ssimonand decipherOnly. 94160814Ssimon 95160814SsimonExamples: 96160814Ssimon 97160814Ssimon keyUsage=digitalSignature, nonRepudiation 98160814Ssimon 99160814Ssimon keyUsage=critical, keyCertSign 100160814Ssimon 101160814Ssimon 102160814Ssimon=head2 Extended Key Usage. 103160814Ssimon 104160814SsimonThis extensions consists of a list of usages indicating purposes for which 105160814Ssimonthe certificate public key can be used for, 106160814Ssimon 107160814SsimonThese can either be object short names of the dotted numerical form of OIDs. 108160814SsimonWhile any OID can be used only certain values make sense. In particular the 109160814Ssimonfollowing PKIX, NS and MS values are meaningful: 110160814Ssimon 111160814Ssimon Value Meaning 112160814Ssimon ----- ------- 113160814Ssimon serverAuth SSL/TLS Web Server Authentication. 114160814Ssimon clientAuth SSL/TLS Web Client Authentication. 115160814Ssimon codeSigning Code signing. 116160814Ssimon emailProtection E-mail Protection (S/MIME). 117160814Ssimon timeStamping Trusted Timestamping 118160814Ssimon msCodeInd Microsoft Individual Code Signing (authenticode) 119160814Ssimon msCodeCom Microsoft Commercial Code Signing (authenticode) 120160814Ssimon msCTLSign Microsoft Trust List Signing 121160814Ssimon msSGC Microsoft Server Gated Crypto 122160814Ssimon msEFS Microsoft Encrypted File System 123160814Ssimon nsSGC Netscape Server Gated Crypto 124160814Ssimon 125160814SsimonExamples: 126160814Ssimon 127160814Ssimon extendedKeyUsage=critical,codeSigning,1.2.3.4 128160814Ssimon extendedKeyUsage=nsSGC,msSGC 129160814Ssimon 130160814Ssimon 131160814Ssimon=head2 Subject Key Identifier. 132160814Ssimon 133160814SsimonThis is really a string extension and can take two possible values. Either 134160814Ssimonthe word B<hash> which will automatically follow the guidelines in RFC3280 135160814Ssimonor a hex string giving the extension value to include. The use of the hex 136160814Ssimonstring is strongly discouraged. 137160814Ssimon 138160814SsimonExample: 139160814Ssimon 140160814Ssimon subjectKeyIdentifier=hash 141160814Ssimon 142160814Ssimon 143160814Ssimon=head2 Authority Key Identifier. 144160814Ssimon 145160814SsimonThe authority key identifier extension permits two options. keyid and issuer: 146160814Ssimonboth can take the optional value "always". 147160814Ssimon 148160814SsimonIf the keyid option is present an attempt is made to copy the subject key 149160814Ssimonidentifier from the parent certificate. If the value "always" is present 150160814Ssimonthen an error is returned if the option fails. 151160814Ssimon 152160814SsimonThe issuer option copies the issuer and serial number from the issuer 153160814Ssimoncertificate. This will only be done if the keyid option fails or 154160814Ssimonis not included unless the "always" flag will always include the value. 155160814Ssimon 156160814SsimonExample: 157160814Ssimon 158160814Ssimon authorityKeyIdentifier=keyid,issuer 159160814Ssimon 160160814Ssimon 161160814Ssimon=head2 Subject Alternative Name. 162160814Ssimon 163160814SsimonThe subject alternative name extension allows various literal values to be 164160814Ssimonincluded in the configuration file. These include B<email> (an email address) 165160814SsimonB<URI> a uniform resource indicator, B<DNS> (a DNS domain name), B<RID> (a 166160814Ssimonregistered ID: OBJECT IDENTIFIER), B<IP> (an IP address), B<dirName> 167160814Ssimon(a distinguished name) and otherName. 168160814Ssimon 169160814SsimonThe email option include a special 'copy' value. This will automatically 170160814Ssimoninclude and email addresses contained in the certificate subject name in 171160814Ssimonthe extension. 172160814Ssimon 173160814SsimonThe IP address used in the B<IP> options can be in either IPv4 or IPv6 format. 174160814Ssimon 175160814SsimonThe value of B<dirName> should point to a section containing the distinguished 176160814Ssimonname to use as a set of name value pairs. Multi values AVAs can be formed by 177160814Ssimonpreceeding the name with a B<+> character. 178160814Ssimon 179160814SsimonotherName can include arbitrary data associated with an OID: the value 180160814Ssimonshould be the OID followed by a semicolon and the content in standard 181160814SsimonASN1_generate_nconf() format. 182160814Ssimon 183160814SsimonExamples: 184160814Ssimon 185160814Ssimon subjectAltName=email:copy,email:my@other.address,URI:http://my.url.here/ 186160814Ssimon subjectAltName=IP:192.168.7.1 187160814Ssimon subjectAltName=IP:13::17 188160814Ssimon subjectAltName=email:my@other.address,RID:1.2.3.4 189160814Ssimon subjectAltName=otherName:1.2.3.4;UTF8:some other identifier 190160814Ssimon 191160814Ssimon subjectAltName=dirName:dir_sect 192160814Ssimon 193160814Ssimon [dir_sect] 194160814Ssimon C=UK 195160814Ssimon O=My Organization 196160814Ssimon OU=My Unit 197160814Ssimon CN=My Name 198160814Ssimon 199160814Ssimon 200160814Ssimon=head2 Issuer Alternative Name. 201160814Ssimon 202160814SsimonThe issuer alternative name option supports all the literal options of 203160814Ssimonsubject alternative name. It does B<not> support the email:copy option because 204160814Ssimonthat would not make sense. It does support an additional issuer:copy option 205160814Ssimonthat will copy all the subject alternative name values from the issuer 206160814Ssimoncertificate (if possible). 207160814Ssimon 208160814SsimonExample: 209160814Ssimon 210160814Ssimon issuserAltName = issuer:copy 211160814Ssimon 212160814Ssimon 213160814Ssimon=head2 Authority Info Access. 214160814Ssimon 215160814SsimonThe authority information access extension gives details about how to access 216160814Ssimoncertain information relating to the CA. Its syntax is accessOID;location 217160814Ssimonwhere I<location> has the same syntax as subject alternative name (except 218160814Ssimonthat email:copy is not supported). accessOID can be any valid OID but only 219160814Ssimoncertain values are meaningful, for example OCSP and caIssuers. 220160814Ssimon 221160814SsimonExample: 222160814Ssimon 223160814Ssimon authorityInfoAccess = OCSP;URI:http://ocsp.my.host/ 224160814Ssimon authorityInfoAccess = caIssuers;URI:http://my.ca/ca.html 225160814Ssimon 226160814Ssimon 227160814Ssimon=head2 CRL distribution points. 228160814Ssimon 229160814SsimonThis is a multi-valued extension that supports all the literal options of 230160814Ssimonsubject alternative name. Of the few software packages that currently interpret 231160814Ssimonthis extension most only interpret the URI option. 232160814Ssimon 233160814SsimonCurrently each option will set a new DistributionPoint with the fullName 234160814Ssimonfield set to the given value. 235160814Ssimon 236160814SsimonOther fields like cRLissuer and reasons cannot currently be set or displayed: 237160814Ssimonat this time no examples were available that used these fields. 238160814Ssimon 239160814SsimonExamples: 240160814Ssimon 241160814Ssimon crlDistributionPoints=URI:http://myhost.com/myca.crl 242160814Ssimon crlDistributionPoints=URI:http://my.com/my.crl,URI:http://oth.com/my.crl 243160814Ssimon 244160814Ssimon=head2 Certificate Policies. 245160814Ssimon 246160814SsimonThis is a I<raw> extension. All the fields of this extension can be set by 247160814Ssimonusing the appropriate syntax. 248160814Ssimon 249160814SsimonIf you follow the PKIX recommendations and just using one OID then you just 250160814Ssimoninclude the value of that OID. Multiple OIDs can be set separated by commas, 251160814Ssimonfor example: 252160814Ssimon 253160814Ssimon certificatePolicies= 1.2.4.5, 1.1.3.4 254160814Ssimon 255160814SsimonIf you wish to include qualifiers then the policy OID and qualifiers need to 256160814Ssimonbe specified in a separate section: this is done by using the @section syntax 257160814Ssimoninstead of a literal OID value. 258160814Ssimon 259160814SsimonThe section referred to must include the policy OID using the name 260160814SsimonpolicyIdentifier, cPSuri qualifiers can be included using the syntax: 261160814Ssimon 262160814Ssimon CPS.nnn=value 263160814Ssimon 264160814SsimonuserNotice qualifiers can be set using the syntax: 265160814Ssimon 266160814Ssimon userNotice.nnn=@notice 267160814Ssimon 268160814SsimonThe value of the userNotice qualifier is specified in the relevant section. 269160814SsimonThis section can include explicitText, organization and noticeNumbers 270160814Ssimonoptions. explicitText and organization are text strings, noticeNumbers is a 271160814Ssimoncomma separated list of numbers. The organization and noticeNumbers options 272160814Ssimon(if included) must BOTH be present. If you use the userNotice option with IE5 273160814Ssimonthen you need the 'ia5org' option at the top level to modify the encoding: 274160814Ssimonotherwise it will not be interpreted properly. 275160814Ssimon 276160814SsimonExample: 277160814Ssimon 278160814Ssimon certificatePolicies=ia5org,1.2.3.4,1.5.6.7.8,@polsect 279160814Ssimon 280160814Ssimon [polsect] 281160814Ssimon 282160814Ssimon policyIdentifier = 1.3.5.8 283160814Ssimon CPS.1="http://my.host.name/" 284160814Ssimon CPS.2="http://my.your.name/" 285160814Ssimon userNotice.1=@notice 286160814Ssimon 287160814Ssimon [notice] 288160814Ssimon 289160814Ssimon explicitText="Explicit Text Here" 290160814Ssimon organization="Organisation Name" 291160814Ssimon noticeNumbers=1,2,3,4 292160814Ssimon 293160814SsimonThe B<ia5org> option changes the type of the I<organization> field. In RFC2459 294160814Ssimonit can only be of type DisplayText. In RFC3280 IA5Strring is also permissible. 295160814SsimonSome software (for example some versions of MSIE) may require ia5org. 296160814Ssimon 297160814Ssimon=head2 Policy Constraints 298160814Ssimon 299160814SsimonThis is a multi-valued extension which consisting of the names 300160814SsimonB<requireExplicitPolicy> or B<inhibitPolicyMapping> and a non negative intger 301160814Ssimonvalue. At least one component must be present. 302160814Ssimon 303160814SsimonExample: 304160814Ssimon 305160814Ssimon policyConstraints = requireExplicitPolicy:3 306160814Ssimon 307160814Ssimon 308160814Ssimon=head2 Inhibit Any Policy 309160814Ssimon 310160814SsimonThis is a string extension whose value must be a non negative integer. 311160814Ssimon 312160814SsimonExample: 313160814Ssimon 314160814Ssimon inhibitAnyPolicy = 2 315160814Ssimon 316160814Ssimon 317160814Ssimon=head2 Name Constraints 318160814Ssimon 319160814SsimonThe name constraints extension is a multi-valued extension. The name should 320160814Ssimonbegin with the word B<permitted> or B<excluded> followed by a B<;>. The rest of 321160814Ssimonthe name and the value follows the syntax of subjectAltName except email:copy 322160814Ssimonis not supported and the B<IP> form should consist of an IP addresses and 323160814Ssimonsubnet mask separated by a B</>. 324160814Ssimon 325160814SsimonExamples: 326160814Ssimon 327160814Ssimon nameConstraints=permitted;IP:192.168.0.0/255.255.0.0 328160814Ssimon 329160814Ssimon nameConstraints=permitted;email:.somedomain.com 330160814Ssimon 331160814Ssimon nameConstraints=excluded;email:.com 332160814Ssimon 333160814Ssimon=head1 DEPRECATED EXTENSIONS 334160814Ssimon 335160814SsimonThe following extensions are non standard, Netscape specific and largely 336160814Ssimonobsolete. Their use in new applications is discouraged. 337160814Ssimon 338160814Ssimon=head2 Netscape String extensions. 339160814Ssimon 340160814SsimonNetscape Comment (B<nsComment>) is a string extension containing a comment 341160814Ssimonwhich will be displayed when the certificate is viewed in some browsers. 342160814Ssimon 343160814SsimonExample: 344160814Ssimon 345160814Ssimon nsComment = "Some Random Comment" 346160814Ssimon 347160814SsimonOther supported extensions in this category are: B<nsBaseUrl>, 348160814SsimonB<nsRevocationUrl>, B<nsCaRevocationUrl>, B<nsRenewalUrl>, B<nsCaPolicyUrl> 349160814Ssimonand B<nsSslServerName>. 350160814Ssimon 351160814Ssimon 352160814Ssimon=head2 Netscape Certificate Type 353160814Ssimon 354160814SsimonThis is a multi-valued extensions which consists of a list of flags to be 355160814Ssimonincluded. It was used to indicate the purposes for which a certificate could 356160814Ssimonbe used. The basicConstraints, keyUsage and extended key usage extensions are 357160814Ssimonnow used instead. 358160814Ssimon 359160814SsimonAcceptable values for nsCertType are: B<client>, B<server>, B<email>, 360160814SsimonB<objsign>, B<reserved>, B<sslCA>, B<emailCA>, B<objCA>. 361160814Ssimon 362160814Ssimon 363160814Ssimon=head1 ARBITRARY EXTENSIONS 364160814Ssimon 365160814SsimonIf an extension is not supported by the OpenSSL code then it must be encoded 366160814Ssimonusing the arbitrary extension format. It is also possible to use the arbitrary 367160814Ssimonformat for supported extensions. Extreme care should be taken to ensure that 368160814Ssimonthe data is formatted correctly for the given extension type. 369160814Ssimon 370160814SsimonThere are two ways to encode arbitrary extensions. 371160814Ssimon 372160814SsimonThe first way is to use the word ASN1 followed by the extension content 373160814Ssimonusing the same syntax as ASN1_generate_nconf(). For example: 374160814Ssimon 375160814Ssimon 1.2.3.4=critical,ASN1:UTF8String:Some random data 376160814Ssimon 377160814Ssimon 1.2.3.4=ASN1:SEQUENCE:seq_sect 378160814Ssimon 379160814Ssimon [seq_sect] 380160814Ssimon 381160814Ssimon field1 = UTF8:field1 382160814Ssimon field2 = UTF8:field2 383160814Ssimon 384160814SsimonIt is also possible to use the word DER to include the raw encoded data in any 385160814Ssimonextension. 386160814Ssimon 387160814Ssimon 1.2.3.4=critical,DER:01:02:03:04 388160814Ssimon 1.2.3.4=DER:01020304 389160814Ssimon 390160814SsimonThe value following DER is a hex dump of the DER encoding of the extension 391160814SsimonAny extension can be placed in this form to override the default behaviour. 392160814SsimonFor example: 393160814Ssimon 394160814Ssimon basicConstraints=critical,DER:00:01:02:03 395160814Ssimon 396160814Ssimon=head1 WARNING 397160814Ssimon 398160814SsimonThere is no guarantee that a specific implementation will process a given 399160814Ssimonextension. It may therefore be sometimes possible to use certificates for 400160814Ssimonpurposes prohibited by their extensions because a specific application does 401160814Ssimonnot recognize or honour the values of the relevant extensions. 402160814Ssimon 403160814SsimonThe DER and ASN1 options should be used with caution. It is possible to create 404160814Ssimontotally invalid extensions if they are not used carefully. 405160814Ssimon 406160814Ssimon 407160814Ssimon=head1 NOTES 408160814Ssimon 409160814SsimonIf an extension is multi-value and a field value must contain a comma the long 410160814Ssimonform must be used otherwise the comma would be misinterpreted as a field 411160814Ssimonseparator. For example: 412160814Ssimon 413160814Ssimon subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar 414160814Ssimon 415160814Ssimonwill produce an error but the equivalent form: 416160814Ssimon 417160814Ssimon subjectAltName=@subject_alt_section 418160814Ssimon 419160814Ssimon [subject_alt_section] 420160814Ssimon subjectAltName=URI:ldap://somehost.com/CN=foo,OU=bar 421160814Ssimon 422160814Ssimonis valid. 423160814Ssimon 424160814SsimonDue to the behaviour of the OpenSSL B<conf> library the same field name 425160814Ssimoncan only occur once in a section. This means that: 426160814Ssimon 427160814Ssimon subjectAltName=@alt_section 428160814Ssimon 429160814Ssimon [alt_section] 430160814Ssimon 431160814Ssimon email=steve@here 432160814Ssimon email=steve@there 433160814Ssimon 434160814Ssimonwill only recognize the last value. This can be worked around by using the form: 435160814Ssimon 436160814Ssimon [alt_section] 437160814Ssimon 438160814Ssimon email.1=steve@here 439160814Ssimon email.2=steve@there 440160814Ssimon 441160814Ssimon=head1 HISTORY 442160814Ssimon 443160814SsimonThe X509v3 extension code was first added to OpenSSL 0.9.2. 444160814Ssimon 445160814SsimonPolicy mappings, inhibit any policy and name constraints support was added in 446160814SsimonOpenSSL 0.9.8 447160814Ssimon 448160814SsimonThe B<directoryName> and B<otherName> option as well as the B<ASN1> option 449160814Ssimonfor arbitrary extensions was added in OpenSSL 0.9.8 450160814Ssimon 451160814Ssimon=head1 SEE ALSO 452160814Ssimon 453160814SsimonL<req(1)|req(1)>, L<ca(1)|ca(1)>, L<x509(1)|x509(1)> 454160814Ssimon 455160814Ssimon 456160814Ssimon=cut 457