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