doc/apps/ca.pod

   1
   2 =pod
   3
   4 =head1 NAME
   5
   6 ca - sample minimal CA application
   7
   8 =head1 SYNOPSIS
   9
  10 B<openssl> B<ca>
  11 [B<-verbose>]
  12 [B<-config filename>]
  13 [B<-name section>]
  14 [B<-gencrl>]
  15 [B<-revoke file>]
  16 [B<-crldays days>]
  17 [B<-crlhours hours>]
  18 [B<-crlexts section>]
  19 [B<-startdate date>]
  20 [B<-enddate date>]
  21 [B<-days arg>]
  22 [B<-md arg>]
  23 [B<-policy arg>]
  24 [B<-keyfile arg>]
  25 [B<-key arg>]
  26 [B<-cert file>]
  27 [B<-in file>]
  28 [B<-out file>]
  29 [B<-outdir dir>]
  30 [B<-infiles>]
  31 [B<-spkac file>]
  32 [B<-ss_cert file>]
  33 [B<-preserveDN>]
  34 [B<-batch>]
  35 [B<-msie_hack>]
  36 [B<-extensions section>]
  37
  38 =head1 DESCRIPTION
  39
  40 The B<ca> command is a minimal CA application. It can be used
  41 to sign certificate requests in a variety of forms and generate
  42 CRLs it also maintains a text database of issued certificates
  43 and their status.
  44
  45 The options descriptions will be divided into each purpose.
  46
  47 =head1 CA OPTIONS
  48
  49 =over 4
  50
  51 =item B<-config filename>
  52
  53 specifies the configuration file to use.
  54
  55 =item B<-in filename>
  56
  57 an input filename containing a single certificate request to be
  58 signed by the CA.
  59
  60 =item B<-ss_cert filename>
  61
  62 a single self signed certificate to be signed by the CA.
  63
  64 =item B<-spkac filename>
  65
  66 a file containing a single Netscape signed public key and challenge
  67 and additional field values to be signed by the CA. See the B<NOTES>
  68 section for information on the required format.
  69
  70 =item B<-infiles>
  71
  72 if present this should be the last option, all subsequent arguments
  73 are assumed to the the names of files containing certificate requests.
  74
  75 =item B<-out filename>
  76
  77 the output file to output certificates to. The default is standard
  78 output. The certificate details will also be printed out to this
  79 file.
  80
  81 =item B<-outdir directory>
  82
  83 the directory to output certificates to. The certificate will be
  84 written to a filename consisting of the serial number in hex with
  85 ".pem" appended.
  86
  87 =item B<-cert>
  88
  89 the CA certificate file.
  90
  91 =item B<-keyfile filename>
  92
  93 the private key to sign requests with.
  94
  95 =item B<-key password>
  96
  97 the password used to encrypt the private key. Since on some
  98 systems the command line arguments are visible (e.g. Unix with
  99 the 'ps' utility) this option should be used with caution.
 100
 101 =item B<-verbose>
 102
 103 this prints extra details about the operations being performed.
 104
 105 =item B<-startdate date>
 106
 107 this allows the start date to be explicitly set. The format of the
 108 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
 109
 110 =item B<-enddate date>
 111
 112 this allows the expiry date to be explicitly set. The format of the
 113 date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure).
 114
 115 =item B<-days arg>
 116
 117 the number of days to certify the certificate for.
 118
 119 =item B<-md alg>
 120
 121 the message digest to use. Possible values include md5, sha1 and mdc2.
 122 This option also applies to CRLs.
 123
 124 =item B<-policy arg>
 125
 126 this option defines the CA "policy" to use. This is a section in
 127 the configuration file which decides which fields should be mandatory
 128 or match the CA certificate. Check out the B<POLICY FORMAT> section
 129 for more information.
 130
 131 =item B<-msie_hack>
 132
 133 this is a legacy option to make B<ca> work with very old versions of
 134 the IE certificate enrollment control "certenr3". It used UniversalStrings
 135 for almost everything. Since the old control has various security bugs
 136 its use is strongly discouraged. The newer control "Xenroll" does not
 137 need this option.
 138
 139 =item B<-preserveDN>
 140
 141 Normally the DN order of a certificate is the same as the order of the
 142 fields in the relevant policy section. When this option is set the order
 143 is the same as the request. This is largely for compatibility with the
 144 older IE enrollment control which would only accept certificates if their
 145 DNs match the order of the request. This is not needed for Xenroll.
 146
 147 =item B<-batch>
 148
 149 this sets the batch mode. In this mode no questions will be asked
 150 and all certificates will be certified automatically.
 151
 152 =item B<-extensions section>
 153
 154 the section of the configuration file containing certificate extensions
 155 to be added when a certificate is issued. If no extension section is
 156 present then a V1 certificate is created. If the extension section
 157 is present (even if it is empty) then a V3 certificate is created.
 158
 159 =back
 160
 161 =head1 CRL OPTIONS
 162
 163 =over 4
 164
 165 =item B<-gencrl>
 166
 167 this option generates a CRL based on information in the index file.
 168
 169 =item B<-crldays num>
 170
 171 the number of days before the next CRL is due. That is the days from
 172 now to place in the CRL nextUpdate field.
 173
 174 =item B<-crlhours num>
 175
 176 the number of hours before the next CRL is due.
 177
 178 =item B<-revoke filename>
 179
 180 a filename containing a certificate to revoke.
 181
 182 =item B<-crlexts section>
 183
 184 the section of the configuration file containing CRL extensions to
 185 include. If no CRL extension section is present then a V1 CRL is
 186 created, if the CRL extension section is present (even if it is
 187 empty) then a V2 CRL is created. The CRL extensions specified are
 188 CRL extensions and B<not> CRL entry extensions.  It should be noted
 189 that some software (for example Netscape) can't handle V2 CRLs.
 190
 191 =back
 192
 193 =head1 CONFIGURATION FILE OPTIONS
 194
 195 The options for B<ca> are contained in the B<ca> section of the
 196 configuration file. Many of these are identical to command line
 197 options. Where the option is present in the configuration file
 198 and the command line the command line value is used. Where an
 199 option is described as mandatory then it must be present in
 200 the configuration file or the command line equivalent (if
 201 any) used.
 202
 203 =over 4
 204
 205 =item B<oid_file>
 206
 207 This specifies a file containing additional B<OBJECT IDENTIFIERS>.
 208 Each line of the file should consist of the numerical form of the
 209 object identifier followed by white space then the short name followed
 210 by white space and finally the long name.
 211
 212 =item B<oid_section>
 213
 214 This specifies a section in the configuration file containing extra
 215 object identifiers. Each line should consist of the short name of the
 216 object identifier followed by B<=> and the numerical form. The short
 217 and long names are the same when this option is used.
 218
 219 =item B<new_certs_dir>
 220
 221 the same as the B<-outdir> command line option. It specifies
 222 the directory where new certificates will be placed. Mandatory.
 223
 224 =item B<certificate>
 225
 226 the same as B<-cert>. It gives the file containing the CA
 227 certificate. Mandatory.
 228
 229 =item B<private_key>
 230
 231 same as the B<-keyfile> option. The file containing the
 232 CA private key. Mandatory.
 233
 234 =item B<RANDFILE>
 235
 236 a file used to read and write random number seed information.
 237
 238 =item B<default_days>
 239
 240 the same as the B<-days> option. The number of days to certify
 241 a certificate for.
 242
 243 =item B<default_startdate>
 244
 245 the same as the B<-startdate> option. The start date to certify
 246 a certificate for. If not set the current time is used.
 247
 248 =item B<default_enddate>
 249
 250 the same as the B<-enddate> option. Either this option or
 251 B<default_days> (or the command line equivalents) must be
 252 present.
 253
 254 =item B<default_crl_hours default_crl_days>
 255
 256 the same as the B<-crlhours> and the B<-crldays> options. These
 257 will only be used if neither command line option is present. At
 258 least one of these must be present to generate a CRL.
 259
 260 =item B<default_md>
 261
 262 the same as the B<-md> option. The message digest to use. Mandatory.
 263
 264 =item B<database>
 265
 266 the text database file to use. Mandatory. This file must be present
 267 though initially it will be empty.
 268
 269 =item B<serialfile>
 270
 271 a text file containing the next serial number to use in hex. Mandatory.
 272 This file must be present and contain a valid serial number.
 273
 274 =item B<x509_extensions>
 275
 276 the same as B<-extensions>.
 277
 278 =item B<crl_extensions>
 279
 280 the same as B<-crlexts>.
 281
 282 =item B<preserve>
 283
 284 the same as B<-preserveDN>
 285
 286 =item B<msie_hack>
 287
 288 the same as B<-msie_hack>
 289
 290 =item B<policy>
 291
 292 the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
 293 for more information.
 294
 295 =back
 296
 297 =head1 POLICY FORMAT
 298
 299 The policy section consists of a set of variables corresponding to
 300 certificate DN fields. If the value is "match" then the field value
 301 must match the same field in the CA certificate. If the value is
 302 "supplied" then it must be present. If the value is "optional" then
 303 it may be present. Any fields not mentioned in the policy section
 304 are silently deleted, unless the B<-preserveDN> option is set but
 305 this can be regarded more of a quirk than intended behaviour.
 306
 307 =head1 SPKAC FORMAT
 308
 309 The input to the B<-spkac> command line option is a Netscape
 310 signed public key and challenge. This will usually come from
 311 the B<KEYGEN> tag in an HTML form to create a new private key.
 312 It is however possible to create SPKACs using the B<spkac> utility.
 313
 314 The file should contain the variable SPKAC set to the value of
 315 the SPKAC and also the required DN components as name value pairs.
 316 If you need to include the same component twice then it can be
 317 preceded by a number and a '.'.
 318
 319 =head1 EXAMPLES
 320
 321 Note: these examples assume that the B<ca> directory structure is
 322 already set up and the relevant files already exist. This usually
 323 involves creating a CA certificate and private key with B<req>, a
 324 serial number file and an empty index file and placing them in
 325 the relevant directories.
 326
 327 To use the sample configuration file below the directories demoCA,
 328 demoCA/private and demoCA/newcerts would be created. The CA
 329 certificate would be copied to demoCA/cacert.pem and its private
 330 key to demoCA/private/cakey.pem. A file demoCA/serial would be
 331 created containing for example "01" and the empty index file
 332 demoCA/index.txt.
 333
 334
 335 Sign a certificate request:
 336
 337 openssl ca -in req.pem -out newcert.pem
 338
 339 Generate a CRL
 340
 341 openssl ca -gencrl -out crl.pem
 342
 343 Sign several requests:
 344
 345 openssl ca -infiles req1.pem req2.pem req3.pem
 346
 347 Certify a Netscape SPKAC:
 348
 349 openssl ca -spkac spkac.txt
 350
 351 A sample SPKAC file (the SPKAC line has been truncated for clarity):
 352
 353  SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
 354  CN=Steve Test
 355  emailAddress=steve@openssl.org
 356  0.OU=OpenSSL Group
 357  1.OU=Another Group
 358
 359 A sample configuration file with the relevant sections for B<ca>:
 360
 361  [ ca ]
 362  default_ca      = CA_default            # The default ca section
 363
 364  [ CA_default ]
 365
 366  dir            = ./demoCA              # top dir
 367  database       = $dir/index.txt        # index file.
 368  new_certs_dir  = $dir/newcerts         # new certs dir
 369
 370  certificate    = $dir/cacert.pem       # The CA cert
 371  serial         = $dir/serial           # serial no file
 372  private_key    = $dir/private/cakey.pem# CA private key
 373  RANDFILE       = $dir/private/.rand    # random number file
 374
 375  default_days   = 365                   # how long to certify for
 376  default_crl_days= 30                   # how long before next CRL
 377  default_md     = md5                   # md to use
 378
 379  policy         = policy_any            # default policy
 380
 381  [ policy_any ]
 382  countryName            = supplied
 383  stateOrProvinceName    = optional
 384  organizationName       = optional
 385  organizationalUnitName = optional
 386  commonName             = supplied
 387  emailAddress           = optional
 388
 389 =head1 WARNINGS
 390
 391 The B<ca> command is quirky and at times downright unfriendly.
 392
 393 The B<ca> utility was originally meant as an example of how to do things
 394 in a CA. It was not supposed be be used as a full blown CA itself:
 395 nevertheless some people are using it for this purpose.
 396
 397 The B<ca> command is effectively a single user command: no locking is
 398 done on the various files and attempts to run more than one B<ca> command
 399 on the same database can have unpredictable results.
 400
 401 =head1 FILES
 402
 403 Note: the location of all files can change either by compile time options,
 404 configuration file entries, environment variables or command line options.
 405 The values below reflect the default values.
 406
 407  /usr/local/ssl/lib/openssl.cnf - master configuration file
 408  ./demoCA                       - main CA directory
 409  ./demoCA/cacert.pem            - CA certificate
 410  ./demoCA/private/cakey.pem     - CA private key
 411  ./demoCA/serial                - CA serial number file
 412  ./demoCA/serial.old            - CA serial number backup file
 413  ./demoCA/index.txt             - CA text database file
 414  ./demoCA/index.txt.old         - CA text database backup file
 415  ./demoCA/certs                 - certificate output file
 416  ./demoCA/.rnd                  - CA random seed information
 417
 418 =head1 ENVIRONMENT VARIABLES
 419
 420 B<OPENSSL_CONF> reflects the location of master configuration file it can
 421 be overridden by the B<-config> command line option.
 422
 423 =head1 RESTRICTIONS
 424
 425 The text database index file is a critical part of the process and
 426 if corrupted it can be difficult to fix. It is theoretically possible
 427 to rebuild the index file from all the issued certificates and a current
 428 CRL: however there is no option to do this.
 429
 430 CRL entry extensions cannot currently be created: only CRL extensions
 431 can be added.
 432
 433 V2 CRL features like delta CRL support and CRL numbers are not currently
 434 supported.
 435
 436 Although several requests can be input and handled at once it is only
 437 possible to include one SPKAC or self signed certificate.
 438
 439 =head1 BUGS
 440
 441 The use of an in memory text database can cause problems when large
 442 numbers of certificates are present because, as the name implies
 443 the database has to be kept in memory.
 444
 445 Certificate request extensions are ignored: some kind of "policy" should
 446 be included to use certain static extensions and certain extensions
 447 from the request.
 448
 449 It is not possible to certify two certificates with the same DN: this
 450 is a side effect of how the text database is indexed and it cannot easily
 451 be fixed without introducing other problems. Some S/MIME clients can use
 452 two certificates with the same DN for separate signing and encryption
 453 keys.
 454
 455 The B<ca> command really needs rewriting or the required functionality
 456 exposed at either a command or interface level so a more friendly utility
 457 (perl script or GUI) can handle things properly. The scripts B<CA.sh> and
 458 B<CA.pl> help a little but not very much.
 459
 460 Any fields in a request that are not present in a policy are silently
 461 deleted. This does not happen if the B<-preserveDN> option is used but
 462 the extra fields are not displayed when the user is asked to certify
 463 a request. The behaviour should be more friendly and configurable.
 464
 465 Cancelling some commands by refusing to certify a certificate can
 466 create an empty file.
 467
 468 =head1 SEE ALSO
 469
 470 req(1), spkac(1), x509(1), CA.pl(1), config(5)
 471
 472 =cut