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