doc/ext-conf.txt

   1 OpenSSL X509V3 extension configuration: preliminary documentation.
   2
   3 INTRODUCTION.
   4
   5 For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
   6 possible to add and print out common X509 V3 certificate and CRL extensions.
   7
   8 For more information about the meaning of extensions see:
   9
  10 http://www.imc.org/ietf-pkix/
  11 http://home.netscape.com/eng/security/certs.html
  12
  13 PRINTING EXTENSIONS.
  14
  15 Extension values are automatically printed out for supported extensions.
  16
  17 openssl x509 -in cert.pem -text
  18 openssl crl -in crl.pem -text
  19
  20 will give information in the extension printout, for example:
  21
  22
  23         X509v3 extensions:
  24             X509v3 Basic Constraints:
  25                 CA:TRUE
  26             X509v3 Subject Key Identifier:
  27                 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
  28             X509v3 Authority Key Identifier:
  29                 keyid:73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15, DirName:/C=AU/ST=Some-State/O=Internet Widgits Pty Ltd/Email=email@1.address/Email=email@2.address, serial:00
  30             X509v3 Key Usage:
  31                 Certificate Sign, CRL Sign
  32             X509v3 Subject Alternative Name:
  33                 email:email@1.address, email:email@2.address
  34
  35 CONFIGURATION FILES.
  36
  37 The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
  38 which certificate extensions to include. In each case a line:
  39
  40 x509_extensions = extension_section
  41
  42 indicates which section contains the extensions. In the case of 'req' the
  43 extension section is used when the -x509 option is present to create a
  44 self signed root certificate.
  45
  46 You can also add extensions to CRLs: a line
  47
  48 crl_extensions = crl_extension_section
  49
  50 will include extensions when the -gencrl option is used with the 'ca' utility.
  51 You can add any extension to a CRL but of the supported extensions only
  52 issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
  53 CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
  54 CRL entry extensions can be displayed.
  55
  56 EXTENSION SYNTAX.
  57
  58 Extensions have the basic form:
  59
  60 extension_name=[critical,] extension_options
  61
  62 the use of the critical option makes the extension critical. Extreme caution
  63 should be made when using the critical flag. If an extension is marked
  64 as critical then any client that does not understand the extension should
  65 reject it as invalid. Some broken software will reject certificates which
  66 have *any* critical extensions (these violates PKIX but we have to live
  67 with it).
  68
  69 There are three main types of extension, string extensions, multi valued
  70 extensions, and raw extensions.
  71
  72 String extensions simply have a string which defines the value of the or how
  73 it is obtained.
  74
  75 For example:
  76
  77 nsComment="This is a Comment"
  78
  79 Multi valued extensions have a short form and a long form. The short form
  80 is a list of names and values:
  81
  82 basicConstraints=critical,CA:true,pathlen:1
  83
  84 The long form allows the values to be placed in a separate section:
  85
  86 basicConstraints=critical,@bs_section
  87
  88 [bs_section]
  89
  90 CA=true
  91 pathlen=1
  92
  93 Both forms are equivalent. However it should be noted that in some cases the
  94 same name can appear multiple times, for example,
  95
  96 subjectAltName=email:steve@here,email:steve@there
  97
  98 in this case an equivalent long form is:
  99
 100 subjectAltName=@alt_section
 101
 102 [alt_section]
 103
 104 email.1=steve@here
 105 email.2=steve@there
 106
 107 This is because the configuration file code cannot handle the same name
 108 occurring twice in the same extension.
 109
 110 Raw extensions allow arbitrary data to be placed in an extension. For
 111 example
 112
 113 1.2.3.4=critical,RAW:01:02:03:04
 114 1.2.3.4=RAW:01020304
 115
 116 The value following RAW is a hex dump of the extension contents. Any extension
 117 can be placed in this form to override the default behaviour. For example:
 118
 119 basicConstraints=critical,RAW:00:01:02:03
 120
 121 WARNING: raw extensions should be used with caution. It is possible to create
 122 totally invalid extensions unless care is taken.
 123
 124 CURRENTLY SUPPORTED EXTENSIONS.
 125
 126 Literal String extensions.
 127
 128 In each case the 'value' of the extension is placed directly in the extension.
 129 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
 130 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and
 131 nsComment.
 132
 133 For example:
 134
 135 nsComment="This is a test comment"
 136
 137 Bit Strings.
 138
 139 Bit string extensions just consist of a list of suppported bits, currently
 140 two extensions are in this category: PKIX keyUsage and the Netscape specific
 141 nsCertType.
 142
 143 nsCertType (netscape certificate type) takes the flags: client, server, email,
 144 objsign, reserved, sslCA, emailCA, objCA.
 145
 146 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
 147 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign,
 148 encipherOnly, decipherOnly.
 149
 150 For example:
 151
 152 nsCertType=server
 153
 154 keyUsage=critical, digitalSignature, nonRepudiation
 155
 156
 157 Basic Constraints.
 158
 159 Basic constraints is a multi valued extension that supports a CA and an
 160 optional pathlen option. The CA option takes the values true and false and
 161 pathlen takes an integer. Note if the CA option is false the pathlen option
 162 should be omitted.
 163
 164 Examples:
 165
 166 basicConstraints=CA:TRUE
 167 basicConstraints=critical,CA:TRUE, pathlen:10
 168
 169 NOTE: for a CA to be considered valid it must have the CA option set to
 170 TRUE. An end user certificate MUST NOT have the CA value set to true.
 171 According to PKIX recommendations it should exclude the extension entirely
 172 however some software may require CA set to FALSE for end entity certificates.
 173
 174 Subject Key Identifier.
 175
 176 This is really a string extension and can take two possible values. Either
 177 a hex string giving details of the extension value to include or the word
 178 'hash' which then automatically follow PKIX guidelines in selecting and
 179 appropriate key identifier. The use of the hex string is strongly discouraged.
 180
 181 Example: subjectKeyIdentifier=hash
 182
 183 Authority Key Identifier.
 184
 185 The authority key identifier extension permits two options. keyid and issuer:
 186 both can take the optional value "always".
 187
 188 If the keyid option is present an attempt is made to copy the subject key
 189 identifier from the parent certificate. If the value "always" is present
 190 then an error is returned if the option fails.
 191
 192 The issuer option copies the issuer and serial number from the issuer
 193 certificate. Normally this will only be done if the keyid option fails or
 194 is not included: the "always" flag will always include the value.
 195
 196 Subject Alternative Name.
 197
 198 The subject alternative name extension allows various literal values to be
 199 included in the configuration file. These include "email" (an email address)
 200 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
 201 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
 202
 203 Also the email option include a special 'copy' value. This will automatically
 204 include and email addresses contained in the certificate subject name in
 205 the extension.
 206
 207 Examples:
 208
 209 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
 210 subjectAltName=email:my@other.address,RID:1.2.3.4
 211
 212 Issuer Alternative Name.
 213
 214 The issuer alternative name option supports all the literal options of
 215 subject alternative name. It does *not* support the email:copy option because
 216 that would not make sense. It does support and additional issuer:copy option
 217 that will copy all the subject alternative name values from the issuer
 218 certificate (if possible).
 219
 220 Display only extensions.
 221
 222 Some extensions are only partially supported and currently are only displayed
 223 but cannot be set. These include private key usage period, CRL number, and
 224 CRL reason.