diff options
Diffstat (limited to 'crypto/openssl/doc/apps/ca.pod')
| -rw-r--r-- | crypto/openssl/doc/apps/ca.pod | 479 |
1 files changed, 479 insertions, 0 deletions
diff --git a/crypto/openssl/doc/apps/ca.pod b/crypto/openssl/doc/apps/ca.pod new file mode 100644 index 0000000..03209aa --- /dev/null +++ b/crypto/openssl/doc/apps/ca.pod @@ -0,0 +1,479 @@ + +=pod + +=head1 NAME + +ca - sample minimal CA application + +=head1 SYNOPSIS + +B<openssl> B<ca> +[B<-verbose>] +[B<-config filename>] +[B<-name section>] +[B<-gencrl>] +[B<-revoke file>] +[B<-crldays days>] +[B<-crlhours hours>] +[B<-crlexts section>] +[B<-startdate date>] +[B<-enddate date>] +[B<-days arg>] +[B<-md arg>] +[B<-policy arg>] +[B<-keyfile arg>] +[B<-key arg>] +[B<-cert file>] +[B<-in file>] +[B<-out file>] +[B<-notext>] +[B<-outdir dir>] +[B<-infiles>] +[B<-spkac file>] +[B<-ss_cert file>] +[B<-preserveDN>] +[B<-batch>] +[B<-msie_hack>] +[B<-extensions section>] + +=head1 DESCRIPTION + +The B<ca> command is a minimal CA application. It can be used +to sign certificate requests in a variety of forms and generate +CRLs it also maintains a text database of issued certificates +and their status. + +The options descriptions will be divided into each purpose. + +=head1 CA OPTIONS + +=over 4 + +=item B<-config filename> + +specifies the configuration file to use. + +=item B<-in filename> + +an input filename containing a single certificate request to be +signed by the CA. + +=item B<-ss_cert filename> + +a single self signed certificate to be signed by the CA. + +=item B<-spkac filename> + +a file containing a single Netscape signed public key and challenge +and additional field values to be signed by the CA. See the B<NOTES> +section for information on the required format. + +=item B<-infiles> + +if present this should be the last option, all subsequent arguments +are assumed to the the names of files containing certificate requests. + +=item B<-out filename> + +the output file to output certificates to. The default is standard +output. The certificate details will also be printed out to this +file. + +=item B<-outdir directory> + +the directory to output certificates to. The certificate will be +written to a filename consisting of the serial number in hex with +".pem" appended. + +=item B<-cert> + +the CA certificate file. + +=item B<-keyfile filename> + +the private key to sign requests with. + +=item B<-key password> + +the password used to encrypt the private key. Since on some +systems the command line arguments are visible (e.g. Unix with +the 'ps' utility) this option should be used with caution. + +=item B<-verbose> + +this prints extra details about the operations being performed. + +=item B<-notext> + +don't output the text form of a certificate to the output file. + +=item B<-startdate date> + +this allows the start date to be explicitly set. The format of the +date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). + +=item B<-enddate date> + +this allows the expiry date to be explicitly set. The format of the +date is YYMMDDHHMMSSZ (the same as an ASN1 UTCTime structure). + +=item B<-days arg> + +the number of days to certify the certificate for. + +=item B<-md alg> + +the message digest to use. Possible values include md5, sha1 and mdc2. +This option also applies to CRLs. + +=item B<-policy arg> + +this option defines the CA "policy" to use. This is a section in +the configuration file which decides which fields should be mandatory +or match the CA certificate. Check out the B<POLICY FORMAT> section +for more information. + +=item B<-msie_hack> + +this is a legacy option to make B<ca> work with very old versions of +the IE certificate enrollment control "certenr3". It used UniversalStrings +for almost everything. Since the old control has various security bugs +its use is strongly discouraged. The newer control "Xenroll" does not +need this option. + +=item B<-preserveDN> + +Normally the DN order of a certificate is the same as the order of the +fields in the relevant policy section. When this option is set the order +is the same as the request. This is largely for compatibility with the +older IE enrollment control which would only accept certificates if their +DNs match the order of the request. This is not needed for Xenroll. + +=item B<-batch> + +this sets the batch mode. In this mode no questions will be asked +and all certificates will be certified automatically. + +=item B<-extensions section> + +the section of the configuration file containing certificate extensions +to be added when a certificate is issued. If no extension section is +present then a V1 certificate is created. If the extension section +is present (even if it is empty) then a V3 certificate is created. + +=back + +=head1 CRL OPTIONS + +=over 4 + +=item B<-gencrl> + +this option generates a CRL based on information in the index file. + +=item B<-crldays num> + +the number of days before the next CRL is due. That is the days from +now to place in the CRL nextUpdate field. + +=item B<-crlhours num> + +the number of hours before the next CRL is due. + +=item B<-revoke filename> + +a filename containing a certificate to revoke. + +=item B<-crlexts section> + +the section of the configuration file containing CRL extensions to +include. If no CRL extension section is present then a V1 CRL is +created, if the CRL extension section is present (even if it is +empty) then a V2 CRL is created. The CRL extensions specified are +CRL extensions and B<not> CRL entry extensions. It should be noted +that some software (for example Netscape) can't handle V2 CRLs. + +=back + +=head1 CONFIGURATION FILE OPTIONS + +The options for B<ca> are contained in the B<ca> section of the +configuration file. Many of these are identical to command line +options. Where the option is present in the configuration file +and the command line the command line value is used. Where an +option is described as mandatory then it must be present in +the configuration file or the command line equivalent (if +any) used. + +=over 4 + +=item B<oid_file> + +This specifies a file containing additional B<OBJECT IDENTIFIERS>. +Each line of the file should consist of the numerical form of the +object identifier followed by white space then the short name followed +by white space and finally the long name. + +=item B<oid_section> + +This specifies a section in the configuration file containing extra +object identifiers. Each line should consist of the short name of the +object identifier followed by B<=> and the numerical form. The short +and long names are the same when this option is used. + +=item B<new_certs_dir> + +the same as the B<-outdir> command line option. It specifies +the directory where new certificates will be placed. Mandatory. + +=item B<certificate> + +the same as B<-cert>. It gives the file containing the CA +certificate. Mandatory. + +=item B<private_key> + +same as the B<-keyfile> option. The file containing the +CA private key. Mandatory. + +=item B<RANDFILE> + +a file used to read and write random number seed information, or +an EGD socket (see L<RAND_egd(3)|RAND_egd(3)>). + +=item B<default_days> + +the same as the B<-days> option. The number of days to certify +a certificate for. + +=item B<default_startdate> + +the same as the B<-startdate> option. The start date to certify +a certificate for. If not set the current time is used. + +=item B<default_enddate> + +the same as the B<-enddate> option. Either this option or +B<default_days> (or the command line equivalents) must be +present. + +=item B<default_crl_hours default_crl_days> + +the same as the B<-crlhours> and the B<-crldays> options. These +will only be used if neither command line option is present. At +least one of these must be present to generate a CRL. + +=item B<default_md> + +the same as the B<-md> option. The message digest to use. Mandatory. + +=item B<database> + +the text database file to use. Mandatory. This file must be present +though initially it will be empty. + +=item B<serialfile> + +a text file containing the next serial number to use in hex. Mandatory. +This file must be present and contain a valid serial number. + +=item B<x509_extensions> + +the same as B<-extensions>. + +=item B<crl_extensions> + +the same as B<-crlexts>. + +=item B<preserve> + +the same as B<-preserveDN> + +=item B<msie_hack> + +the same as B<-msie_hack> + +=item B<policy> + +the same as B<-policy>. Mandatory. See the B<POLICY FORMAT> section +for more information. + +=back + +=head1 POLICY FORMAT + +The policy section consists of a set of variables corresponding to +certificate DN fields. If the value is "match" then the field value +must match the same field in the CA certificate. If the value is +"supplied" then it must be present. If the value is "optional" then +it may be present. Any fields not mentioned in the policy section +are silently deleted, unless the B<-preserveDN> option is set but +this can be regarded more of a quirk than intended behaviour. + +=head1 SPKAC FORMAT + +The input to the B<-spkac> command line option is a Netscape +signed public key and challenge. This will usually come from +the B<KEYGEN> tag in an HTML form to create a new private key. +It is however possible to create SPKACs using the B<spkac> utility. + +The file should contain the variable SPKAC set to the value of +the SPKAC and also the required DN components as name value pairs. +If you need to include the same component twice then it can be +preceded by a number and a '.'. + +=head1 EXAMPLES + +Note: these examples assume that the B<ca> directory structure is +already set up and the relevant files already exist. This usually +involves creating a CA certificate and private key with B<req>, a +serial number file and an empty index file and placing them in +the relevant directories. + +To use the sample configuration file below the directories demoCA, +demoCA/private and demoCA/newcerts would be created. The CA +certificate would be copied to demoCA/cacert.pem and its private +key to demoCA/private/cakey.pem. A file demoCA/serial would be +created containing for example "01" and the empty index file +demoCA/index.txt. + + +Sign a certificate request: + + openssl ca -in req.pem -out newcert.pem + +Generate a CRL + + openssl ca -gencrl -out crl.pem + +Sign several requests: + + openssl ca -infiles req1.pem req2.pem req3.pem + +Certify a Netscape SPKAC: + + openssl ca -spkac spkac.txt + +A sample SPKAC file (the SPKAC line has been truncated for clarity): + + SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 + CN=Steve Test + emailAddress=steve@openssl.org + 0.OU=OpenSSL Group + 1.OU=Another Group + +A sample configuration file with the relevant sections for B<ca>: + + [ ca ] + default_ca = CA_default # The default ca section + + [ CA_default ] + + dir = ./demoCA # top dir + database = $dir/index.txt # index file. + new_certs_dir = $dir/newcerts # new certs dir + + certificate = $dir/cacert.pem # The CA cert + serial = $dir/serial # serial no file + private_key = $dir/private/cakey.pem# CA private key + RANDFILE = $dir/private/.rand # random number file + + default_days = 365 # how long to certify for + default_crl_days= 30 # how long before next CRL + default_md = md5 # md to use + + policy = policy_any # default policy + + [ policy_any ] + countryName = supplied + stateOrProvinceName = optional + organizationName = optional + organizationalUnitName = optional + commonName = supplied + emailAddress = optional + +=head1 WARNINGS + +The B<ca> command is quirky and at times downright unfriendly. + +The B<ca> utility was originally meant as an example of how to do things +in a CA. It was not supposed be be used as a full blown CA itself: +nevertheless some people are using it for this purpose. + +The B<ca> command is effectively a single user command: no locking is +done on the various files and attempts to run more than one B<ca> command +on the same database can have unpredictable results. + +=head1 FILES + +Note: the location of all files can change either by compile time options, +configuration file entries, environment variables or command line options. +The values below reflect the default values. + + /usr/local/ssl/lib/openssl.cnf - master configuration file + ./demoCA - main CA directory + ./demoCA/cacert.pem - CA certificate + ./demoCA/private/cakey.pem - CA private key + ./demoCA/serial - CA serial number file + ./demoCA/serial.old - CA serial number backup file + ./demoCA/index.txt - CA text database file + ./demoCA/index.txt.old - CA text database backup file + ./demoCA/certs - certificate output file + ./demoCA/.rnd - CA random seed information + +=head1 ENVIRONMENT VARIABLES + +B<OPENSSL_CONF> reflects the location of master configuration file it can +be overridden by the B<-config> command line option. + +=head1 RESTRICTIONS + +The text database index file is a critical part of the process and +if corrupted it can be difficult to fix. It is theoretically possible +to rebuild the index file from all the issued certificates and a current +CRL: however there is no option to do this. + +CRL entry extensions cannot currently be created: only CRL extensions +can be added. + +V2 CRL features like delta CRL support and CRL numbers are not currently +supported. + +Although several requests can be input and handled at once it is only +possible to include one SPKAC or self signed certificate. + +=head1 BUGS + +The use of an in memory text database can cause problems when large +numbers of certificates are present because, as the name implies +the database has to be kept in memory. + +Certificate request extensions are ignored: some kind of "policy" should +be included to use certain static extensions and certain extensions +from the request. + +It is not possible to certify two certificates with the same DN: this +is a side effect of how the text database is indexed and it cannot easily +be fixed without introducing other problems. Some S/MIME clients can use +two certificates with the same DN for separate signing and encryption +keys. + +The B<ca> command really needs rewriting or the required functionality +exposed at either a command or interface level so a more friendly utility +(perl script or GUI) can handle things properly. The scripts B<CA.sh> and +B<CA.pl> help a little but not very much. + +Any fields in a request that are not present in a policy are silently +deleted. This does not happen if the B<-preserveDN> option is used but +the extra fields are not displayed when the user is asked to certify +a request. The behaviour should be more friendly and configurable. + +Cancelling some commands by refusing to certify a certificate can +create an empty file. + +=head1 SEE ALSO + +L<req(1)|req(1)>, L<spkac(1)|spkac(1)>, L<x509(1)|x509(1)>, L<CA.pl(1)|CA.pl(1)>, +L<config(5)|config(5)> + +=cut |
