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