ca.pod revision 68651
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<-crldays days>] 17[B<-crlhours hours>] 18[B<-crlexts section>] 19[B<-startdate date>] 20[B<-enddate date>] 21[B<-days arg>] 22[B<-md arg>] 23[B<-policy arg>] 24[B<-keyfile arg>] 25[B<-key arg>] 26[B<-passin arg>] 27[B<-cert file>] 28[B<-in file>] 29[B<-out file>] 30[B<-notext>] 31[B<-outdir dir>] 32[B<-infiles>] 33[B<-spkac file>] 34[B<-ss_cert file>] 35[B<-preserveDN>] 36[B<-batch>] 37[B<-msie_hack>] 38[B<-extensions section>] 39 40=head1 DESCRIPTION 41 42The B<ca> command is a minimal CA application. It can be used 43to sign certificate requests in a variety of forms and generate 44CRLs it also maintains a text database of issued certificates 45and their status. 46 47The options descriptions will be divided into each purpose. 48 49=head1 CA OPTIONS 50 51=over 4 52 53=item B<-config filename> 54 55specifies the configuration file to use. 56 57=item B<-in filename> 58 59an input filename containing a single certificate request to be 60signed by the CA. 61 62=item B<-ss_cert filename> 63 64a single self signed certificate to be signed by the CA. 65 66=item B<-spkac filename> 67 68a file containing a single Netscape signed public key and challenge 69and additional field values to be signed by the CA. See the B<NOTES> 70section for information on the required format. 71 72=item B<-infiles> 73 74if present this should be the last option, all subsequent arguments 75are assumed to the the names of files containing certificate requests. 76 77=item B<-out filename> 78 79the output file to output certificates to. The default is standard 80output. The certificate details will also be printed out to this 81file. 82 83=item B<-outdir directory> 84 85the directory to output certificates to. The certificate will be 86written to a filename consisting of the serial number in hex with 87".pem" appended. 88 89=item B<-cert> 90 91the CA certificate file. 92 93=item B<-keyfile filename> 94 95the private key to sign requests with. 96 97=item B<-key password> 98 99the password used to encrypt the private key. Since on some 100systems the command line arguments are visible (e.g. Unix with 101the 'ps' utility) this option should be used with caution. 102 103=item B<-passin arg> 104 105the key password source. For more information about the format of B<arg> 106see the B<PASS PHRASE ARGUMENTS> section in L<openssl(1)|openssl(1)>. 107=item B<-verbose> 108 109this prints extra details about the operations being performed. 110 111=item B<-notext> 112 113don't output the text form of a certificate to the output file. 114 115=item B<-startdate date> 116 117this allows the start date to be explicitly set. The format of the 118date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). 119 120=item B<-enddate date> 121 122this allows the expiry date to be explicitly set. The format of the 123date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). 124 125=item B<-days arg> 126 127the number of days to certify the certificate for. 128 129=item B<-md alg> 130 131the message digest to use. Possible values include md5, sha1 and mdc2. 132This option also applies to CRLs. 133 134=item B<-policy arg> 135 136this option defines the CA "policy" to use. This is a section in 137the configuration file which decides which fields should be mandatory 138or match the CA certificate. Check out the B<POLICY FORMAT> section 139for more information. 140 141=item B<-msie_hack> 142 143this is a legacy option to make B<ca> work with very old versions of 144the IE certificate enrollment control "certenr3". It used UniversalStrings 145for almost everything. Since the old control has various security bugs 146its use is strongly discouraged. The newer control "Xenroll" does not 147need this option. 148 149=item B<-preserveDN> 150 151Normally the DN order of a certificate is the same as the order of the 152fields in the relevant policy section. When this option is set the order 153is the same as the request. This is largely for compatibility with the 154older IE enrollment control which would only accept certificates if their 155DNs match the order of the request. This is not needed for Xenroll. 156 157=item B<-batch> 158 159this sets the batch mode. In this mode no questions will be asked 160and all certificates will be certified automatically. 161 162=item B<-extensions section> 163 164the section of the configuration file containing certificate extensions 165to be added when a certificate is issued. If no extension section is 166present then a V1 certificate is created. If the extension section 167is present (even if it is empty) then a V3 certificate is created. 168 169=back 170 171=head1 CRL OPTIONS 172 173=over 4 174 175=item B<-gencrl> 176 177this option generates a CRL based on information in the index file. 178 179=item B<-crldays num> 180 181the number of days before the next CRL is due. That is the days from 182now to place in the CRL nextUpdate field. 183 184=item B<-crlhours num> 185 186the number of hours before the next CRL is due. 187 188=item B<-revoke filename> 189 190a filename containing a certificate to revoke. 191 192=item B<-crlexts section> 193 194the section of the configuration file containing CRL extensions to 195include. If no CRL extension section is present then a V1 CRL is 196created, if the CRL extension section is present (even if it is 197empty) then a V2 CRL is created. The CRL extensions specified are 198CRL extensions and B<not> CRL entry extensions. It should be noted 199that some software (for example Netscape) can't handle V2 CRLs. 200 201=back 202 203=head1 CONFIGURATION FILE OPTIONS 204 205The options for B<ca> are contained in the B<ca> section of the 206configuration file. Many of these are identical to command line 207options. Where the option is present in the configuration file 208and the command line the command line value is used. Where an 209option is described as mandatory then it must be present in 210the configuration file or the command line equivalent (if 211any) used. 212 213=over 4 214 215=item B<oid_file> 216 217This specifies a file containing additional B<OBJECT IDENTIFIERS>. 218Each line of the file should consist of the numerical form of the 219object identifier followed by white space then the short name followed 220by white space and finally the long name. 221 222=item B<oid_section> 223 224This specifies a section in the configuration file containing extra 225object identifiers. Each line should consist of the short name of the 226object identifier followed by B<=> and the numerical form. The short 227and long names are the same when this option is used. 228 229=item B<new_certs_dir> 230 231the same as the B<-outdir> command line option. It specifies 232the directory where new certificates will be placed. Mandatory. 233 234=item B<certificate> 235 236the same as B<-cert>. It gives the file containing the CA 237certificate. Mandatory. 238 239=item B<private_key> 240 241same as the B<-keyfile> option. The file containing the 242CA private key. Mandatory. 243 244=item B<RANDFILE> 245 246a file used to read and write random number seed information, or 247an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). 248 249=item B<default_days> 250 251the same as the B<-days> option. The number of days to certify 252a certificate for. 253 254=item B<default_startdate> 255 256the same as the B<-startdate> option. The start date to certify 257a certificate for. If not set the current time is used. 258 259=item B<default_enddate> 260 261the same as the B<-enddate> option. Either this option or 262B<default_days> (or the command line equivalents) must be 263present. 264 265=item B<default_crl_hours default_crl_days> 266 267the same as the B<-crlhours> and the B<-crldays> options. These 268will only be used if neither command line option is present. At 269least one of these must be present to generate a CRL. 270 271=item B<default_md> 272 273the same as the B<-md> option. The message digest to use. Mandatory. 274 275=item B<database> 276 277the text database file to use. Mandatory. This file must be present 278though initially it will be empty. 279 280=item B<serialfile> 281 282a text file containing the next serial number to use in hex. Mandatory. 283This file must be present and contain a valid serial number. 284 285=item B<x509_extensions> 286 287the same as B<-extensions>. 288 289=item B<crl_extensions> 290 291the same as B<-crlexts>. 292 293=item B<preserve> 294 295the same as B<-preserveDN> 296 297=item B<msie_hack> 298 299the same as B<-msie_hack> 300 301=item B<policy> 302 303the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section 304for more information. 305 306=back 307 308=head1 POLICY FORMAT 309 310The policy section consists of a set of variables corresponding to 311certificate DN fields. If the value is "match" then the field value 312must match the same field in the CA certificate. If the value is 313"supplied" then it must be present. If the value is "optional" then 314it may be present. Any fields not mentioned in the policy section 315are silently deleted, unless the B<-preserveDN> option is set but 316this can be regarded more of a quirk than intended behaviour. 317 318=head1 SPKAC FORMAT 319 320The input to the B<-spkac> command line option is a Netscape 321signed public key and challenge. This will usually come from 322the B<KEYGEN> tag in an HTML form to create a new private key. 323It is however possible to create SPKACs using the B<spkac> utility. 324 325The file should contain the variable SPKAC set to the value of 326the SPKAC and also the required DN components as name value pairs. 327If you need to include the same component twice then it can be 328preceded by a number and a '.'. 329 330=head1 EXAMPLES 331 332Note: these examples assume that the B<ca> directory structure is 333already set up and the relevant files already exist. This usually 334involves creating a CA certificate and private key with B<req>, a 335serial number file and an empty index file and placing them in 336the relevant directories. 337 338To use the sample configuration file below the directories demoCA, 339demoCA/private and demoCA/newcerts would be created. The CA 340certificate would be copied to demoCA/cacert.pem and its private 341key to demoCA/private/cakey.pem. A file demoCA/serial would be 342created containing for example "01" and the empty index file 343demoCA/index.txt. 344 345 346Sign a certificate request: 347 348 openssl ca -in req.pem -out newcert.pem 349 350Sign a certificate request, using CA extensions: 351 352 openssl ca -in req.pem -extensions v3_ca -out newcert.pem 353 354Generate a CRL 355 356 openssl ca -gencrl -out crl.pem 357 358Sign several requests: 359 360 openssl ca -infiles req1.pem req2.pem req3.pem 361 362Certify a Netscape SPKAC: 363 364 openssl ca -spkac spkac.txt 365 366A sample SPKAC file (the SPKAC line has been truncated for clarity): 367 368 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 369 CN=Steve Test 370 emailAddress=steve@openssl.org 371 0.OU=OpenSSL Group 372 1.OU=Another Group 373 374A sample configuration file with the relevant sections for B<ca>: 375 376 [ ca ] 377 default_ca = CA_default # The default ca section 378 379 [ CA_default ] 380 381 dir = ./demoCA # top dir 382 database = $dir/index.txt # index file. 383 new_certs_dir = $dir/newcerts # new certs dir 384 385 certificate = $dir/cacert.pem # The CA cert 386 serial = $dir/serial # serial no file 387 private_key = $dir/private/cakey.pem# CA private key 388 RANDFILE = $dir/private/.rand # random number file 389 390 default_days = 365 # how long to certify for 391 default_crl_days= 30 # how long before next CRL 392 default_md = md5 # md to use 393 394 policy = policy_any # default policy 395 396 [ policy_any ] 397 countryName = supplied 398 stateOrProvinceName = optional 399 organizationName = optional 400 organizationalUnitName = optional 401 commonName = supplied 402 emailAddress = optional 403 404=head1 WARNINGS 405 406The B<ca> command is quirky and at times downright unfriendly. 407 408The B<ca> utility was originally meant as an example of how to do things 409in a CA. It was not supposed be be used as a full blown CA itself: 410nevertheless some people are using it for this purpose. 411 412The B<ca> command is effectively a single user command: no locking is 413done on the various files and attempts to run more than one B<ca> command 414on the same database can have unpredictable results. 415 416=head1 FILES 417 418Note: the location of all files can change either by compile time options, 419configuration file entries, environment variables or command line options. 420The values below reflect the default values. 421 422 /usr/local/ssl/lib/openssl.cnf - master configuration file 423 ./demoCA - main CA directory 424 ./demoCA/cacert.pem - CA certificate 425 ./demoCA/private/cakey.pem - CA private key 426 ./demoCA/serial - CA serial number file 427 ./demoCA/serial.old - CA serial number backup file 428 ./demoCA/index.txt - CA text database file 429 ./demoCA/index.txt.old - CA text database backup file 430 ./demoCA/certs - certificate output file 431 ./demoCA/.rnd - CA random seed information 432 433=head1 ENVIRONMENT VARIABLES 434 435B<OPENSSL_CONF> reflects the location of master configuration file it can 436be overridden by the B<-config> command line option. 437 438=head1 RESTRICTIONS 439 440The text database index file is a critical part of the process and 441if corrupted it can be difficult to fix. It is theoretically possible 442to rebuild the index file from all the issued certificates and a current 443CRL: however there is no option to do this. 444 445CRL entry extensions cannot currently be created: only CRL extensions 446can be added. 447 448V2 CRL features like delta CRL support and CRL numbers are not currently 449supported. 450 451Although several requests can be input and handled at once it is only 452possible to include one SPKAC or self signed certificate. 453 454=head1 BUGS 455 456The use of an in memory text database can cause problems when large 457numbers of certificates are present because, as the name implies 458the database has to be kept in memory. 459 460Certificate request extensions are ignored: some kind of "policy" should 461be included to use certain static extensions and certain extensions 462from the request. 463 464It is not possible to certify two certificates with the same DN: this 465is a side effect of how the text database is indexed and it cannot easily 466be fixed without introducing other problems. Some S/MIME clients can use 467two certificates with the same DN for separate signing and encryption 468keys. 469 470The B<ca> command really needs rewriting or the required functionality 471exposed at either a command or interface level so a more friendly utility 472(perl script or GUI) can handle things properly. The scripts B<CA.sh> and 473B<CA.pl> help a little but not very much. 474 475Any fields in a request that are not present in a policy are silently 476deleted. This does not happen if the B<-preserveDN> option is used but 477the extra fields are not displayed when the user is asked to certify 478a request. The behaviour should be more friendly and configurable. 479 480Cancelling some commands by refusing to certify a certificate can 481create an empty file. 482 483=head1 SEE ALSO 484 485L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, 486L<config(5)|config(5)> 487 488=cut 489