doc/man/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 encrrypt 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 compatability 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<new_certs_dir>
 206
 207 the same as the B<-outdir> command line option. It specifies
 208 the directory where new certificates will be placed. Mandatory.
 209
 210 =item B<certificate>
 211
 212 the same as B<-cert>. It gives the file containing the CA
 213 certificate. Mandatory.
 214
 215 =item B<private_key>
 216
 217 same as the B<-keyfile> option. The file containing the
 218 CA private key. Mandatory.
 219
 220 =item B<RANDFILE>
 221
 222 a file used to read and write random number seed information.
 223
 224 =item B<default_days>
 225
 226 the same as the B<-days> option. The number of days to certify
 227 a certificate for.
 228
 229 =item B<default_startdate>
 230
 231 the same as the B<-startdate> option. The start date to certify
 232 a certificate for. If not set the current time is used.
 233
 234 =item B<default_enddate>
 235
 236 the same as the B<-enddate> option. Either this option or
 237 B<default_days> (or the command line equivalents) must be
 238 present.
 239
 240 =item B<default_crl_hours default_crl_days>
 241
 242 the same as the B<-crlhours> and the B<-crldays> options. These
 243 will only be used if neither command line option is present. At
 244 least one of these must be present to generate a CRL.
 245
 246 =item B<default_md>
 247
 248 the same as the B<-md> option. The message digest to use. Mandatory.
 249
 250 =item B<database>
 251
 252 the text database file to use. Mandatory. This file must be present
 253 though initially it will be empty.
 254
 255 =item B<serialfile>
 256
 257 a text file containing the next serial number to use in hex. Mandatory.
 258 This file must be present and contain a valid serial number.
 259
 260 =item B<x509_extensions>
 261
 262 the same as B<-extensions>.
 263
 264 =item B<crl_extensions>
 265
 266 the same as B<-crlexts>.
 267
 268 =item B<preserve>
 269
 270 the same as B<-preserveDN>
 271
 272 =item B<msie_hack>
 273
 274 the same as B<-msie_hack>
 275
 276 =item B<policy>
 277
 278 the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section
 279 for more information.
 280
 281 =back
 282
 283 =head1 POLICY FORMAT
 284
 285 The policy section consists of a set of variables corresponding to
 286 certificate DN fields. If the value is "match" then the field value
 287 must match the same field in the CA certificate. If the value is
 288 "supplied" then it must be present. If the value is "optional" then
 289 it may be present. Any fields not mentioned in the policy section
 290 are silently deleted, unless the B<-preserveDN> option is set but
 291 this can be regarded more of a quirk than intended behaviour.
 292
 293 =head1 SPKAC FORMAT
 294
 295 The input to the B<-spkac> command line option is a Netscape
 296 signed public key and challenge. This will usually come from
 297 the B<KEYGEN> tag in an HTML form to create a new private key.
 298 It is however possible to create SPKACs using the B<spkac> utility.
 299
 300 The file should contain the variable SPKAC set to the value of
 301 the SPKAC and also the required DN components as name value pairs.
 302 If you need to include the same component twice then it can be
 303 preceded by a number and a '.'.
 304
 305 =head1 EXAMPLES
 306
 307 Note: these examples assume that the B<ca> directory structure is
 308 already set up and the relevant files already exist. This usually
 309 involves creating a CA certificate and private key with B<req>, a
 310 serial number file and an empty index file and placing them in
 311 the relevant directories.
 312
 313 To use the sample configuration file below the directories demoCA,
 314 demoCA/private and demoCA/newcerts would be created. The CA
 315 certificate would be copied to demoCA/cacert.pem and its private
 316 key to demoCA/private/cakey.pem. A file demoCA/serial would be
 317 created containing for example "01" and the empty index file
 318 demoCA/index.txt.
 319
 320
 321 Sign a certificate request:
 322
 323 openssl ca -in req.pem -out newcert.pem
 324
 325 Generate a CRL
 326
 327 openssl ca -gencrl -out crl.pem
 328
 329 Sign several requests:
 330
 331 openssl ca -infiles req1.pem req2.pem req3.pem
 332
 333 Certify a Netscape SPKAC:
 334
 335 openssl ca -spkac spkac.txt
 336
 337 A sample SPKAC file (the SPKAC line has been truncated for clarity):
 338
 339  SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5
 340  CN=Steve Test
 341  emailAddress=steve@openssl.org
 342  0.OU=OpenSSL Group
 343  1.OU=Another Group
 344
 345 A sample configuration file with the relevant sections for B<ca>:
 346
 347  [ ca ]
 348  default_ca      = CA_default            # The default ca section
 349
 350  [ CA_default ]
 351
 352  dir            = ./demoCA              # top dir
 353  database       = $dir/index.txt        # index file.
 354  new_certs_dir  = $dir/newcerts         # new certs dir
 355
 356  certificate    = $dir/cacert.pem       # The CA cert
 357  serial         = $dir/serial           # serial no file
 358  private_key    = $dir/private/cakey.pem# CA private key
 359  RANDFILE       = $dir/private/.rand    # random number file
 360
 361  default_days   = 365                   # how long to certify for
 362  default_crl_days= 30                   # how long before next CRL
 363  default_md     = md5                   # md to use
 364
 365  policy         = policy_any            # default policy
 366
 367  [ policy_any ]
 368  countryName            = supplied
 369  stateOrProvinceName    = optional
 370  organizationName       = optional
 371  organizationalUnitName = optional
 372  commonName             = supplied
 373  emailAddress           = optional
 374
 375 =head1 WARNINGS
 376
 377 The B<ca> command is quirky and at times downright unfriendly.
 378
 379 The B<ca> utility was originally meant as an example of how to do things
 380 in a CA. It was not supposed be be used as a full blown CA itself:
 381 nevertheless some people are using it for this purpose.
 382
 383 The B<ca> command is effectively a single user command: no locking is
 384 done on the various files and attempts to run more than one B<ca> command
 385 on the same database can have unpredictable results.
 386
 387 =head1 FILES
 388
 389 Note: the location of all files can change either by compile time options,
 390 configration file entries, environment variables or command line options.
 391 The values below reflect the default values.
 392
 393  /usr/local/ssl/lib/openssl.cnf - master configuration file
 394  ./demoCA                       - main CA directory
 395  ./demoCA/cacert.pem            - CA certificate
 396  ./demoCA/private/cakey.pem     - CA private key
 397  ./demoCA/serial                - CA serial number file
 398  ./demoCA/serial.old            - CA serial number backup file
 399  ./demoCA/index.txt             - CA text database file
 400  ./demoCA/index.txt.old         - CA text database backup file
 401  ./demoCA/certs                 - certificate output file
 402  ./demoCA/.rnd                  - CA random seed information
 403
 404 =head1 ENVIRONMENT VARIABLES
 405
 406 B<OPENSSL_CONF> reflects the location of master configuration file it can
 407 be overridden by the B<-config> command line option.
 408
 409 =head1 RESTRICTIONS
 410
 411 The text database index file is a critical part of the process and
 412 if corrupted it can be difficult to fix. It is theoretically possible
 413 to rebuild the index file from all the issued certificates and a current
 414 CRL: however there is no option to do this.
 415
 416 CRL entry extensions cannot currently be created: only CRL extensions
 417 can be added.
 418
 419 V2 CRL features like delta CRL support and CRL numbers are not currently
 420 supported.
 421
 422 Although several requests can be input and handled at once it is only
 423 possible to include one SPKAC or self signed certificate.
 424
 425 =head1 BUGS
 426
 427 The use of an in memory text database can cause problems when large
 428 numbers of certificates are present because, as the name implies
 429 the database has to be kept in memory.
 430
 431 Certificate request extensions are ignored: some kind of "policy" should
 432 be included to use certain static extensions and certain extensions
 433 from the request.
 434
 435 It is not possible to certify two certificates with the same DN: this
 436 is a side effect of how the text database is indexed and it cannot easily
 437 be fixed without introducing other problems. Netscape apparently can use
 438 two certificates with the same DN for separate signing and encryption
 439 keys.
 440
 441 The B<ca> command really needs rewriting or the required functionality
 442 exposed at either a command or interface level so a more friendly utility
 443 (perl script or GUI) can handle things properly. The scripts B<CA.sh> and
 444 B<CA.pl> help a little but not very much.
 445
 446 Any fields in a request that are not present in a policy are silently
 447 deleted. This does not happen if the B<-preserveDN> option is used but
 448 the extra fields are not displayed when the user is asked to certify
 449 a request. The behaviour should be more friendly and configurable.
 450
 451 Cancelling some commands by refusing to certify a certificate can
 452 create an empty file.
 453
 454 =head1 SEE ALSO
 455
 456 req(1), spkac(1), x509(1), CA.pl(1), config(5)
 457
 458 =cut