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