Mon Feb 3 10:00:53 2003
Standard preamble:
======================================================================
\\$1
.. ..
.... Set up some character translations and predefined strings. \*(-- will
give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
double quote, and \*(R" will give a right double quote. | will give a
real vertical bar. \*(C+ will give a nicer C++. Capital omega is used
to do unbreakable dashes and therefore won't be available. \*(C` and
\*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\}
If the F register is turned on, we'll generate index entries on stderr
for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
index entries marked with X<> in POD. Of course, you'll have to process
the output yourself in some meaningful fashion.
. de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\}
For nroff, turn off justification. Always turn off hyphenation; it
makes way too many mistakes in technical documents.
Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
Fear. Run. Save yourself. No user-serviceable parts.
.bd B 3 . \" fudge factors for nroff and troff . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] .\} . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents . \" corrections for vroff . \" for low resolution devices (crt and lpr) \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} ======================================================================
Title "CA 1"
The options descriptions will be divided into each purpose.
Many of the configuration file options 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. p "oid_file" 4 Item "oid_file" This specifies a file containing additional \s-1OBJECT\s0 \s-1IDENTIFIERS\s0. 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. p "oid_section" 4 Item "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 = and the numerical form. The short and long names are the same when this option is used. p "new_certs_dir" 4 Item "new_certs_dir" the same as the -outdir command line option. It specifies the directory where new certificates will be placed. Mandatory. p "certificate" 4 Item "certificate" the same as -cert. It gives the file containing the \s-1CA\s0 certificate. Mandatory. p "private_key" 4 Item "private_key" same as the -keyfile option. The file containing the \s-1CA\s0 private key. Mandatory. p "\s-1RANDFILE\s0" 4 Item "RANDFILE" a file used to read and write random number seed information, or an \s-1EGD\s0 socket (see RAND_egd(3)). p "default_days" 4 Item "default_days" the same as the -days option. The number of days to certify a certificate for. p "default_startdate" 4 Item "default_startdate" the same as the -startdate option. The start date to certify a certificate for. If not set the current time is used. p "default_enddate" 4 Item "default_enddate" the same as the -enddate option. Either this option or \fBdefault_days (or the command line equivalents) must be present. p "default_crl_hours default_crl_days" 4 Item "default_crl_hours default_crl_days" the same as the -crlhours and the -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 \s-1CRL\s0. p "default_md" 4 Item "default_md" the same as the -md option. The message digest to use. Mandatory. p "database" 4 Item "database" the text database file to use. Mandatory. This file must be present though initially it will be empty. p "serialfile" 4 Item "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. p "x509_extensions" 4 Item "x509_extensions" the same as -extensions. p "crl_extensions" 4 Item "crl_extensions" the same as -crlexts. p "preserve" 4 Item "preserve" the same as -preserveDN p "email_in_dn" 4 Item "email_in_dn" the same as -noemailDN. If you want the \s-1EMAIL\s0 field to be removed from the \s-1DN\s0 of the certificate simply set this to 'no'. If not present the default is to allow for the \s-1EMAIL\s0 filed in the certificate's \s-1DN\s0. p "msie_hack" 4 Item "msie_hack" the same as -msie_hack p "policy" 4 Item "policy" the same as -policy. Mandatory. See the \s-1POLICY\s0 \s-1FORMAT\s0 section for more information. p "nameopt, certopt" 4 Item "nameopt, certopt" these options allow the format used to display the certificate details when asking the user to confirm signing. All the options supported by the x509 utilities -nameopt and -certopt switches can be used here, except the no_signame and no_sigdump are permanently set and cannot be disabled (this is because the certificate signature cannot be displayed because the certificate has not been signed at this point). .Sp For convenience the values default_ca are accepted by both to produce a reasonable output. .Sp If neither option is present the format used in earlier versions of OpenSSL is used. Use of the old format is strongly discouraged because it only displays fields mentioned in the policy section, mishandles multicharacter string types and does not display extensions. p "copy_extensions" 4 Item "copy_extensions" determines how extensions in certificate requests should be handled. If set to none or this option is not present then extensions are ignored and not copied to the certificate. If set to copy then any extensions present in the request that are not already present are copied to the certificate. If set to copyall then all extensions in the request are copied to the certificate: if the extension is already present in the certificate it is deleted first. See the \s-1WARNINGS\s0 section before using this option. .Sp The main use of this option is to allow a certificate request to supply values for certain extensions such as subjectAltName.
The file should contain the variable \s-1SPKAC\s0 set to the value of the \s-1SPKAC\s0 and also the required \s-1DN\s0 components as name value pairs. If you need to include the same component twice then it can be preceded by a number and a '.'.
To use the sample configuration file below the directories demoCA, demoCA/private and demoCA/newcerts would be created. The \s-1CA\s0 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 \*(L"01\*(R" and the empty index file demoCA/index.txt.
Sign a certificate request:
.Vb 1 openssl ca -in req.pem -out newcert.pem .Ve Sign a certificate request, using \s-1CA\s0 extensions:
.Vb 1 openssl ca -in req.pem -extensions v3_ca -out newcert.pem .Ve Generate a \s-1CRL\s0
.Vb 1 openssl ca -gencrl -out crl.pem .Ve Sign several requests:
.Vb 1 openssl ca -infiles req1.pem req2.pem req3.pem .Ve Certify a Netscape \s-1SPKAC:\s0
.Vb 1 openssl ca -spkac spkac.txt .Ve A sample \s-1SPKAC\s0 file (the \s-1SPKAC\s0 line has been truncated for clarity):
.Vb 5 SPKAC=MIG0MGAwXDANBgkqhkiG9w0BAQEFAANLADBIAkEAn7PDhCeV/xIxUg8V70YRxK2A5 CN=Steve Test emailAddress=steve@openssl.org 0.OU=OpenSSL Group 1.OU=Another Group .Ve A sample configuration file with the relevant sections for ca:
.Vb 2 [ ca ] default_ca = CA_default # The default ca section .Ve .Vb 1 [ CA_default ] .Ve .Vb 3 dir = ./demoCA # top dir database = $dir/index.txt # index file. new_certs_dir = $dir/newcerts # new certs dir .Ve .Vb 4 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 .Ve .Vb 3 default_days = 365 # how long to certify for default_crl_days= 30 # how long before next CRL default_md = md5 # md to use .Ve .Vb 2 policy = policy_any # default policy email_in_dn = no # Don't add the email into cert DN .Ve .Vb 3 nameopt = default_ca # Subject name display option certopt = default_ca # Certificate display option copy_extensions = none # Don't copy extensions from request .Ve .Vb 7 [ policy_any ] countryName = supplied stateOrProvinceName = optional organizationName = optional organizationalUnitName = optional commonName = supplied emailAddress = optional .Ve
.Vb 10 /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 .Ve
V2 \s-1CRL\s0 features like delta \s-1CRL\s0 support and \s-1CRL\s0 numbers are not currently supported.
Although several requests can be input and handled at once it is only possible to include one \s-1SPKAC\s0 or self signed certificate.
It is not possible to certify two certificates with the same \s-1DN:\s0 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 \s-1DN\s0 for separate signing and encryption keys.
The 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 \s-1GUI\s0) can handle things properly. The scripts \s-1CA\s0.sh and \fB\s-1CA\s0.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 -preserveDN option is used. To enforce the absence of the \s-1EMAIL\s0 field within the \s-1DN\s0, as suggested by RFCs, regardless the contents of the request' subject the -noemailDN option can be used. The behaviour should be more friendly and configurable.
Cancelling some commands by refusing to certify a certificate can create an empty file.
The ca utility was originally meant as an example of how to do things in a \s-1CA\s0. It was not supposed to be used as a full blown \s-1CA\s0 itself: nevertheless some people are using it for this purpose.
The ca command is effectively a single user command: no locking is done on the various files and attempts to run more than one ca command on the same database can have unpredictable results.
The copy_extensions option should be used with caution. If care is not taken then it can be a security risk. For example if a certificate request contains a basicConstraints extension with \s-1CA:TRUE\s0 and the \fBcopy_extensions value is set to copyall and the user does not spot this when the certificate is displayed then this will hand the requestor a valid \s-1CA\s0 certificate.
This situation can be avoided by setting copy_extensions to copy and including basicConstraints with \s-1CA:FALSE\s0 in the configuration file. Then if the request contains a basicConstraints extension it will be ignored.
It is advisable to also include values for other extensions such as keyUsage to prevent a request supplying its own values.
Additional restrictions can be placed on the \s-1CA\s0 certificate itself. For example if the \s-1CA\s0 certificate has:
.Vb 1 basicConstraints = CA:TRUE, pathlen:0 .Ve then even if a certificate is issued with \s-1CA:TRUE\s0 it will not be valid.