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