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