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