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