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