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 x509 -in cert.pem -text
  18 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 EXTENSION SYNTAX.
  47
  48 Extensions have the basic form:
  49
  50 extension_name=[critical,] extension_options
  51
  52 the use of the critical option makes the extension critical. Extreme caution
  53 should be made when using the critical flag. If an extension is marked
  54 as critical then any client that does not understand the extension should
  55 reject it as invalid. Some broken software will reject certificates which
  56 have *any* critical extensions (these violates PKIX but we have to live
  57 with it).
  58
  59 There are three main types of extension, string extensions, multi valued
  60 extensions, and raw extensions.
  61
  62 String extensions simply have a string which defines the value of the or how
  63 it is obtained.
  64
  65 For example:
  66
  67 nsComment="This is a Comment"
  68
  69 Multi valued extensions have a short form and a long form. The short form
  70 is a list of names and values:
  71
  72 basicConstraints=critical,CA:true,pathlen:1
  73
  74 The long form allows the values to be placed in a separate section:
  75
  76 basicConstraints=critical,@bs_section
  77
  78 [bs_section]
  79
  80 CA=true
  81 pathlen=1
  82
  83 Both forms are equivalent. However it should be noted that in some cases the
  84 same name can appear multiple times, for example,
  85
  86 subjectAltName=email:steve@here,email:steve@there
  87
  88 in this case an equivalent long form is:
  89
  90 subjectAltName=@alt_section
  91
  92 [alt_section]
  93
  94 email.1=steve@here
  95 email.2=steve@there
  96
  97 This is because the configuration file code cannot handle the same name
  98 occurring twice in the same extension.
  99
 100 Raw extensions allow arbitrary data to be placed in an extension. For
 101 example
 102
 103 1.2.3.4=critical,RAW:01:02:03:04
 104 1.2.3.4=RAW:01020304
 105
 106 The value following RAW is a hex dump of the extension contents. Any extension
 107 can be placed in this form to override the default behaviour. For example:
 108
 109 basicConstraints=critical,RAW:00:01:02:03
 110
 111 WARNING: raw extensions should be used with caution. It is possible to create
 112 totally invalid extensions unless care is taken.
 113
 114 CURRENTLY SUPPORTED EXTENSIONS.
 115
 116 Literal String extensions.
 117
 118 In each case the 'value' of the extension is placed directly in the extension.
 119 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
 120 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and
 121 nsComment.
 122
 123 For example:
 124
 125 nsComment="This is a test comment"
 126
 127 Bit Strings.
 128
 129 Bit string extensions just consist of a list of suppported bits, currently
 130 two extensions are in this category: PKIX keyUsage and the Netscape specific
 131 nsCertType.
 132
 133 nsCertType (netscape certificate type) takes the flags: client, server, email,
 134 objsign, reserved, sslCA, emailCA, objCA.
 135
 136 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
 137 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLCertSign,
 138 encipherOnly, decipherOnly.
 139
 140 For example:
 141
 142 nsCertType=server
 143
 144 keyUsage=critical, digitalSignature, nonRepudiation
 145
 146
 147 Basic Constraints.
 148
 149 Basic constraints is a multi valued extension that supports a CA and an
 150 optional pathlen option. The CA option takes the values true and false and
 151 pathlen takes an integer. Note if the CA option is false the pathlen option
 152 should be omitted.
 153
 154 Examples:
 155
 156 basicConstraints=CA:TRUE
 157 basicConstraints=critical,CA:TRUE, pathlen:10
 158
 159 NOTE: for a CA to be considered valid it must have the CA option set to
 160 TRUE. An end user certificate MUST NOT have the CA value set to true.
 161 According to PKIX recommendations it should exclude the extension entirely
 162 however some software may require CA set to FALSE for end entity certificates.
 163
 164 Subject Key Identifier.
 165
 166 This is really a string extension and can take two possible values. Either
 167 a hex string giving details of the extension value to include or the word
 168 'hash' which then automatically follow PKIX guidelines in selecting and
 169 appropriate key identifier. The use of the hex string is strongly discouraged.
 170
 171 Example: subjectKeyIdentifier=hash
 172
 173 Authority Key Identifier.
 174
 175 The authority key identifier extension permits two options. keyid and issuer:
 176 both can take the optional value "always".
 177
 178 If the keyid option is present an attempt is made to copy the subject key
 179 identifier from the parent certificate. If the value "always" is present
 180 then an error is returned if the option fails.
 181
 182 The issuer option copies the issuer and serial number from the issuer
 183 certificate. Normally this will only be done if the keyid option fails or
 184 is not included: the "always" flag will always include the value.
 185
 186 Subject Alternative Name.
 187
 188 The subject alternative name extension allows various literal values to be
 189 included in the configuration file. These include "email" (an email address)
 190 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
 191 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
 192
 193 Also the email option include a special 'copy' value. This will automatically
 194 include and email addresses contained in the certificate subject name in
 195 the extension.
 196
 197 Examples:
 198
 199 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
 200 subjectAltName=email:my@other.address,RID:1.2.3.4
 201
 202 Issuer Alternative Name.
 203
 204 The issuer alternative name option supports all the literal options of
 205 subject alternative name. It does *not* support the email:copy option because
 206 that would not make sense. It does support and additional issuer:copy option
 207 that will copy all the subject alternative name values from the issuer
 208 certificate (if possible).
 209
 210 Display only extensions.
 211
 212 Some extensions are only partially supported and currently are only displayed
 213 but cannot be set. These include private key usage period, CRL number, and
 214 CRL reason.