doc/openssl.txt

   1
   2 This is some preliminary documentation for OpenSSL.
   3
   4 ==============================================================================
   5                             BUFFER Library
   6 ==============================================================================
   7
   8 [Note: I wrote this when I saw a Malloc version of strdup() in there which
   9  I'd written myself anyway. I was so annoyed at not noticing this I decided to
  10  document it :-) Steve.]
  11
  12 The buffer library handles simple character arrays. Buffers are used for various
  13 purposes in the library, most notably memory BIOs.
  14
  15 The library uses the BUF_MEM structure defined in buffer.h:
  16
  17 typedef struct buf_mem_st
  18         {
  19         int length;     /* current number of bytes */
  20         char *data;
  21         int max;        /* size of buffer */
  22         } BUF_MEM;
  23
  24 'length' is the current size of the buffer in bytes, 'max' is the amount of
  25 memory allocated to the buffer. There are three functions which handle these
  26 and one "miscelanous" function.
  27
  28 BUF_MEM *BUF_MEM_new()
  29
  30 This allocates a new buffer of zero size. Returns the buffer or NULL on error.
  31
  32 void BUF_MEM_free(BUF_MEM *a)
  33
  34 This frees up an already existing buffer. The data is zeroed before freeing
  35 up in case the buffer contains sensitive data.
  36
  37 int BUF_MEM_grow(BUF_MEM *str, int len)
  38
  39 This changes the size of an already existing buffer. It returns zero on error
  40 or the new size (i.e. 'len'). Any data already in the buffer is preserved if
  41 it increases in size.
  42
  43 char * BUF_strdup(char *str)
  44
  45 This is the previously mentioned strdup function: like the standard library
  46 strdup() it copies a null terminated string into a block of allocated memory
  47 and returns a pointer to the allocated block.
  48
  49 Unlike the standard C library strdup() this function uses Malloc() and so
  50 should be used in preference to the standard library strdup() because it can
  51 be used for memory leak checking or replacing the malloc() function.
  52
  53 The memory allocated from BUF_strdup() should be freed up using the Free()
  54 function.
  55
  56 ==============================================================================
  57                OpenSSL X509V3 extension configuration
  58 ==============================================================================
  59
  60 OpenSSL X509V3 extension configuration: preliminary documentation.
  61
  62 INTRODUCTION.
  63
  64 For OpenSSL 0.9.2 the extension code has be considerably enhanced. It is now
  65 possible to add and print out common X509 V3 certificate and CRL extensions.
  66
  67 For more information about the meaning of extensions see:
  68
  69 http://www.imc.org/ietf-pkix/
  70 http://home.netscape.com/eng/security/certs.html
  71
  72 PRINTING EXTENSIONS.
  73
  74 Extension values are automatically printed out for supported extensions.
  75
  76 openssl x509 -in cert.pem -text
  77 openssl crl -in crl.pem -text
  78
  79 will give information in the extension printout, for example:
  80
  81
  82         X509v3 extensions:
  83             X509v3 Basic Constraints:
  84                 CA:TRUE
  85             X509v3 Subject Key Identifier:
  86                 73:FE:F7:59:A7:E1:26:84:44:D6:44:36:EE:79:1A:95:7C:B1:4B:15
  87             X509v3 Authority Key Identifier:
  88                 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
  89             X509v3 Key Usage:
  90                 Certificate Sign, CRL Sign
  91             X509v3 Subject Alternative Name:
  92                 email:email@1.address, email:email@2.address
  93
  94 CONFIGURATION FILES.
  95
  96 The OpenSSL utilities 'ca' and 'req' can now have extension sections listing
  97 which certificate extensions to include. In each case a line:
  98
  99 x509_extensions = extension_section
 100
 101 indicates which section contains the extensions. In the case of 'req' the
 102 extension section is used when the -x509 option is present to create a
 103 self signed root certificate.
 104
 105 You can also add extensions to CRLs: a line
 106
 107 crl_extensions = crl_extension_section
 108
 109 will include extensions when the -gencrl option is used with the 'ca' utility.
 110 You can add any extension to a CRL but of the supported extensions only
 111 issuerAltName and authorityKeyIdentifier make any real sense. Note: these are
 112 CRL extensions NOT CRL *entry* extensions which cannot currently be generated.
 113 CRL entry extensions can be displayed.
 114
 115 EXTENSION SYNTAX.
 116
 117 Extensions have the basic form:
 118
 119 extension_name=[critical,] extension_options
 120
 121 the use of the critical option makes the extension critical. Extreme caution
 122 should be made when using the critical flag. If an extension is marked
 123 as critical then any client that does not understand the extension should
 124 reject it as invalid. Some broken software will reject certificates which
 125 have *any* critical extensions (these violates PKIX but we have to live
 126 with it).
 127
 128 There are three main types of extension, string extensions, multi valued
 129 extensions, and raw extensions.
 130
 131 String extensions simply have a string which defines the value of the or how
 132 it is obtained.
 133
 134 For example:
 135
 136 nsComment="This is a Comment"
 137
 138 Multi valued extensions have a short form and a long form. The short form
 139 is a list of names and values:
 140
 141 basicConstraints=critical,CA:true,pathlen:1
 142
 143 The long form allows the values to be placed in a separate section:
 144
 145 basicConstraints=critical,@bs_section
 146
 147 [bs_section]
 148
 149 CA=true
 150 pathlen=1
 151
 152 Both forms are equivalent. However it should be noted that in some cases the
 153 same name can appear multiple times, for example,
 154
 155 subjectAltName=email:steve@here,email:steve@there
 156
 157 in this case an equivalent long form is:
 158
 159 subjectAltName=@alt_section
 160
 161 [alt_section]
 162
 163 email.1=steve@here
 164 email.2=steve@there
 165
 166 This is because the configuration file code cannot handle the same name
 167 occurring twice in the same extension.
 168
 169 Raw extensions allow arbitrary data to be placed in an extension. For
 170 example
 171
 172 1.2.3.4=critical,RAW:01:02:03:04
 173 1.2.3.4=RAW:01020304
 174
 175 The value following RAW is a hex dump of the extension contents. Any extension
 176 can be placed in this form to override the default behaviour. For example:
 177
 178 basicConstraints=critical,RAW:00:01:02:03
 179
 180 WARNING: raw extensions should be used with caution. It is possible to create
 181 totally invalid extensions unless care is taken.
 182
 183 CURRENTLY SUPPORTED EXTENSIONS.
 184
 185 Literal String extensions.
 186
 187 In each case the 'value' of the extension is placed directly in the extension.
 188 Currently supported extensions in this category are: nsBaseUrl, nsRevocationUrl
 189 nsCaRevocationUrl, nsRenewalUrl, nsCaPolicyUrl, nsSslServerName and
 190 nsComment.
 191
 192 For example:
 193
 194 nsComment="This is a test comment"
 195
 196 Bit Strings.
 197
 198 Bit string extensions just consist of a list of suppported bits, currently
 199 two extensions are in this category: PKIX keyUsage and the Netscape specific
 200 nsCertType.
 201
 202 nsCertType (netscape certificate type) takes the flags: client, server, email,
 203 objsign, reserved, sslCA, emailCA, objCA.
 204
 205 keyUsage (PKIX key usage) takes the flags: digitalSignature, nonRepudiation,
 206 keyEncipherment, dataEncipherment, keyAgreement, keyCertSign, cRLSign,
 207 encipherOnly, decipherOnly.
 208
 209 For example:
 210
 211 nsCertType=server
 212
 213 keyUsage=critical, digitalSignature, nonRepudiation
 214
 215
 216 Basic Constraints.
 217
 218 Basic constraints is a multi valued extension that supports a CA and an
 219 optional pathlen option. The CA option takes the values true and false and
 220 pathlen takes an integer. Note if the CA option is false the pathlen option
 221 should be omitted.
 222
 223 Examples:
 224
 225 basicConstraints=CA:TRUE
 226 basicConstraints=critical,CA:TRUE, pathlen:10
 227
 228 NOTE: for a CA to be considered valid it must have the CA option set to
 229 TRUE. An end user certificate MUST NOT have the CA value set to true.
 230 According to PKIX recommendations it should exclude the extension entirely
 231 however some software may require CA set to FALSE for end entity certificates.
 232
 233 Subject Key Identifier.
 234
 235 This is really a string extension and can take two possible values. Either
 236 a hex string giving details of the extension value to include or the word
 237 'hash' which then automatically follow PKIX guidelines in selecting and
 238 appropriate key identifier. The use of the hex string is strongly discouraged.
 239
 240 Example: subjectKeyIdentifier=hash
 241
 242 Authority Key Identifier.
 243
 244 The authority key identifier extension permits two options. keyid and issuer:
 245 both can take the optional value "always".
 246
 247 If the keyid option is present an attempt is made to copy the subject key
 248 identifier from the parent certificate. If the value "always" is present
 249 then an error is returned if the option fails.
 250
 251 The issuer option copies the issuer and serial number from the issuer
 252 certificate. Normally this will only be done if the keyid option fails or
 253 is not included: the "always" flag will always include the value.
 254
 255 Subject Alternative Name.
 256
 257 The subject alternative name extension allows various literal values to be
 258 included in the configuration file. These include "email" (an email address)
 259 "URI" a uniform resource indicator, "DNS" (a DNS domain name), RID (a
 260 registered ID: OBJECT IDENTIFIER) and IP (and IP address).
 261
 262 Also the email option include a special 'copy' value. This will automatically
 263 include and email addresses contained in the certificate subject name in
 264 the extension.
 265
 266 Examples:
 267
 268 subjectAltName=email:copy,email:my@other.address,URL:http://my.url.here/
 269 subjectAltName=email:my@other.address,RID:1.2.3.4
 270
 271 Issuer Alternative Name.
 272
 273 The issuer alternative name option supports all the literal options of
 274 subject alternative name. It does *not* support the email:copy option because
 275 that would not make sense. It does support an additional issuer:copy option
 276 that will copy all the subject alternative name values from the issuer
 277 certificate (if possible).
 278
 279 CRL distribution points.
 280
 281 This is a multivalued extension that supports all the literal options of
 282 subject alternative name. Of the few software packages that currently interpret
 283 this extension most only interpret the URI option.
 284
 285 Currently each option will set a new DistributionPoint with the fullName
 286 field set to the given value.
 287
 288 Other fields like cRLissuer and reasons cannot currently be set or displayed:
 289 at this time no examples were available that used these fields.
 290
 291 If you see this extension with <UNSUPPORTED> when you attempt to print it out
 292 or it doesn't appear to display correctly then let me know, including the
 293 certificate (mail me at steve@openssl.org) .
 294
 295 Examples:
 296
 297 crlDistributionPoints=URI:http://www.myhost.com/myca.crl
 298 crlDistributionPoints=URI:http://www.my.com/my.crl,URI:http://www.oth.com/my.crl
 299
 300 Certificate Policies.
 301
 302 This is a RAW extension. It attempts to display the contents of this extension:
 303 unfortuntately this extension is often improperly encoded.
 304
 305 The certificate policies extension will rarely be used in practice: few
 306 software packages interpret it correctly or at all.
 307
 308 All the fields of this extension can be set by using the appropriate syntax.
 309
 310 If you follow the PKIX recommendations of not including any qualifiers and just
 311 using only one OID then you just include the value of that OID. Multiple OIDs
 312 can be set separated by commas, for example:
 313
 314 certificatePolicies= 1.2.4.5, 1.1.3.4
 315
 316 If you wish to include qualifiers then the policy OID and qualifiers need to
 317 be specified in a separate section: this is done by using the @section syntax
 318 instead of a literal OID value.
 319
 320 The section referred to must include the policy OID using the name
 321 policyIdentifier, cPSuri qualifiers can be included using the syntax:
 322
 323 CPS.nnn=value
 324
 325 userNotice qualifiers can be set using the syntax:
 326
 327 userNotice.nnn=@notice
 328
 329 The value of the userNotice qualifier is specified in the relevant section. This
 330 section can include explicitText, organization and noticeNumbers options.
 331 explicitText and organization are text strings, noticeNumbers is a comma
 332 separated list of numbers. The organization and noticeNumbers options (if
 333 included) must BOTH be present.
 334
 335 Example:
 336
 337 certificatePolicies=1.2.3.4,1.5.6.7.8,@polsect
 338
 339 [polsect]
 340
 341 policyIdentifier = 1.3.5.8
 342 CPS.1="http://my.host.name/"
 343 CPS.2="http://my.your.name/"
 344 userNotice.1=@notice
 345
 346 [notice]
 347
 348 explicitText="Explicit Text Here"
 349 organization="Organisation Name"
 350 noticeNumbers=1,2,3,4
 351
 352 Display only extensions.
 353
 354 Some extensions are only partially supported and currently are only displayed
 355 but cannot be set. These include private key usage period, CRL number, and
 356 CRL reason.
 357