ca.pod revision 325337
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 427=item B<serial> 428 429a text file containing the next serial number to use in hex. Mandatory. 430This file must be present and contain a valid serial number. 431 432=item B<crlnumber> 433 434a text file containing the next CRL number to use in hex. The crl number 435will be inserted in the CRLs only if this file exists. If this file is 436present, it must contain a valid CRL number. 437 438=item B<x509_extensions> 439 440the same as B<-extensions>. 441 442=item B<crl_extensions> 443 444the same as B<-crlexts>. 445 446=item B<preserve> 447 448the same as B<-preserveDN> 449 450=item B<email_in_dn> 451 452the same as B<-noemailDN>. If you want the EMAIL field to be removed 453from the DN of the certificate simply set this to 'no'. If not present 454the default is to allow for the EMAIL filed in the certificate's DN. 455 456=item B<msie_hack> 457 458the same as B<-msie_hack> 459 460=item B<policy> 461 462the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section 463for more information. 464 465=item B<name_opt>, B<cert_opt> 466 467these options allow the format used to display the certificate details 468when asking the user to confirm signing. All the options supported by 469the B<x509> utilities B<-nameopt> and B<-certopt> switches can be used 470here, except the B<no_signame> and B<no_sigdump> are permanently set 471and cannot be disabled (this is because the certificate signature cannot 472be displayed because the certificate has not been signed at this point). 473 474For convenience the values B<ca_default> are accepted by both to produce 475a reasonable output. 476 477If neither option is present the format used in earlier versions of 478OpenSSL is used. Use of the old format is B<strongly> discouraged because 479it only displays fields mentioned in the B<policy> section, mishandles 480multicharacter string types and does not display extensions. 481 482=item B<copy_extensions> 483 484determines how extensions in certificate requests should be handled. 485If set to B<none> or this option is not present then extensions are 486ignored and not copied to the certificate. If set to B<copy> then any 487extensions present in the request that are not already present are copied 488to the certificate. If set to B<copyall> then all extensions in the 489request are copied to the certificate: if the extension is already present 490in the certificate it is deleted first. See the B<WARNINGS> section before 491using this option. 492 493The main use of this option is to allow a certificate request to supply 494values for certain extensions such as subjectAltName. 495 496=back 497 498=head1 POLICY FORMAT 499 500The policy section consists of a set of variables corresponding to 501certificate DN fields. If the value is "match" then the field value 502must match the same field in the CA certificate. If the value is 503"supplied" then it must be present. If the value is "optional" then 504it may be present. Any fields not mentioned in the policy section 505are silently deleted, unless the B<-preserveDN> option is set but 506this can be regarded more of a quirk than intended behaviour. 507 508=head1 SPKAC FORMAT 509 510The input to the B<-spkac> command line option is a Netscape 511signed public key and challenge. This will usually come from 512the B<KEYGEN> tag in an HTML form to create a new private key. 513It is however possible to create SPKACs using the B<spkac> utility. 514 515The file should contain the variable SPKAC set to the value of 516the SPKAC and also the required DN components as name value pairs. 517If you need to include the same component twice then it can be 518preceded by a number and a '.'. 519 520When processing SPKAC format, the output is DER if the B<-out> 521flag is used, but PEM format if sending to stdout or the B<-outdir> 522flag is used. 523 524=head1 EXAMPLES 525 526Note: these examples assume that the B<ca> directory structure is 527already set up and the relevant files already exist. This usually 528involves creating a CA certificate and private key with B<req>, a 529serial number file and an empty index file and placing them in 530the relevant directories. 531 532To use the sample configuration file below the directories demoCA, 533demoCA/private and demoCA/newcerts would be created. The CA 534certificate would be copied to demoCA/cacert.pem and its private 535key to demoCA/private/cakey.pem. A file demoCA/serial would be 536created containing for example "01" and the empty index file 537demoCA/index.txt. 538 539 540Sign a certificate request: 541 542 openssl ca -in req.pem -out newcert.pem 543 544Sign a certificate request, using CA extensions: 545 546 openssl ca -in req.pem -extensions v3_ca -out newcert.pem 547 548Generate a CRL 549 550 openssl ca -gencrl -out crl.pem 551 552Sign several requests: 553 554 openssl ca -infiles req1.pem req2.pem req3.pem 555 556Certify a Netscape SPKAC: 557 558 openssl ca -spkac spkac.txt 559 560A sample SPKAC file (the SPKAC line has been truncated for clarity): 561 562 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 563 CN=Steve Test 564 emailAddress=steve@openssl.org 565 0.OU=OpenSSL Group 566 1.OU=Another Group 567 568A sample configuration file with the relevant sections for B<ca>: 569 570 [ ca ] 571 default_ca = CA_default # The default ca section 572 573 [ CA_default ] 574 575 dir = ./demoCA # top dir 576 database = $dir/index.txt # index file. 577 new_certs_dir = $dir/newcerts # new certs dir 578 579 certificate = $dir/cacert.pem # The CA cert 580 serial = $dir/serial # serial no file 581 private_key = $dir/private/cakey.pem# CA private key 582 RANDFILE = $dir/private/.rand # random number file 583 584 default_days = 365 # how long to certify for 585 default_crl_days= 30 # how long before next CRL 586 default_md = md5 # md to use 587 588 policy = policy_any # default policy 589 email_in_dn = no # Don't add the email into cert DN 590 591 name_opt = ca_default # Subject name display option 592 cert_opt = ca_default # Certificate display option 593 copy_extensions = none # Don't copy extensions from request 594 595 [ policy_any ] 596 countryName = supplied 597 stateOrProvinceName = optional 598 organizationName = optional 599 organizationalUnitName = optional 600 commonName = supplied 601 emailAddress = optional 602 603=head1 FILES 604 605Note: the location of all files can change either by compile time options, 606configuration file entries, environment variables or command line options. 607The values below reflect the default values. 608 609 /usr/local/ssl/lib/openssl.cnf - master configuration file 610 ./demoCA - main CA directory 611 ./demoCA/cacert.pem - CA certificate 612 ./demoCA/private/cakey.pem - CA private key 613 ./demoCA/serial - CA serial number file 614 ./demoCA/serial.old - CA serial number backup file 615 ./demoCA/index.txt - CA text database file 616 ./demoCA/index.txt.old - CA text database backup file 617 ./demoCA/certs - certificate output file 618 ./demoCA/.rnd - CA random seed information 619 620=head1 ENVIRONMENT VARIABLES 621 622B<OPENSSL_CONF> reflects the location of master configuration file it can 623be overridden by the B<-config> command line option. 624 625=head1 RESTRICTIONS 626 627The text database index file is a critical part of the process and 628if corrupted it can be difficult to fix. It is theoretically possible 629to rebuild the index file from all the issued certificates and a current 630CRL: however there is no option to do this. 631 632V2 CRL features like delta CRLs are not currently supported. 633 634Although several requests can be input and handled at once it is only 635possible to include one SPKAC or self signed certificate. 636 637=head1 BUGS 638 639The use of an in memory text database can cause problems when large 640numbers of certificates are present because, as the name implies 641the database has to be kept in memory. 642 643The B<ca> command really needs rewriting or the required functionality 644exposed at either a command or interface level so a more friendly utility 645(perl script or GUI) can handle things properly. The scripts B<CA.sh> and 646B<CA.pl> help a little but not very much. 647 648Any fields in a request that are not present in a policy are silently 649deleted. This does not happen if the B<-preserveDN> option is used. To 650enforce the absence of the EMAIL field within the DN, as suggested by 651RFCs, regardless the contents of the request' subject the B<-noemailDN> 652option can be used. The behaviour should be more friendly and 653configurable. 654 655Cancelling some commands by refusing to certify a certificate can 656create an empty file. 657 658=head1 WARNINGS 659 660The B<ca> command is quirky and at times downright unfriendly. 661 662The B<ca> utility was originally meant as an example of how to do things 663in a CA. It was not supposed to be used as a full blown CA itself: 664nevertheless some people are using it for this purpose. 665 666The B<ca> command is effectively a single user command: no locking is 667done on the various files and attempts to run more than one B<ca> command 668on the same database can have unpredictable results. 669 670The B<copy_extensions> option should be used with caution. If care is 671not taken then it can be a security risk. For example if a certificate 672request contains a basicConstraints extension with CA:TRUE and the 673B<copy_extensions> value is set to B<copyall> and the user does not spot 674this when the certificate is displayed then this will hand the requestor 675a valid CA certificate. 676 677This situation can be avoided by setting B<copy_extensions> to B<copy> 678and including basicConstraints with CA:FALSE in the configuration file. 679Then if the request contains a basicConstraints extension it will be 680ignored. 681 682It is advisable to also include values for other extensions such 683as B<keyUsage> to prevent a request supplying its own values. 684 685Additional restrictions can be placed on the CA certificate itself. 686For example if the CA certificate has: 687 688 basicConstraints = CA:TRUE, pathlen:0 689 690then even if a certificate is issued with CA:TRUE it will not be valid. 691 692=head1 SEE ALSO 693 694L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, 695L<config(5)|config(5)>, L<x509v3_config(5)|x509v3_config(5)> 696 697=cut 698