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