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