From ecacd12edb99d739f012912174233320c5f8262f Mon Sep 17 00:00:00 2001 From: markm Date: Tue, 28 Jan 2003 22:58:14 +0000 Subject: Update for OpenSSL 0.9.7. No assembler code at the moment. This will follow. --- secure/usr.bin/openssl/man/ca.1 | 694 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 694 insertions(+) create mode 100644 secure/usr.bin/openssl/man/ca.1 (limited to 'secure/usr.bin/openssl/man/ca.1') diff --git a/secure/usr.bin/openssl/man/ca.1 b/secure/usr.bin/openssl/man/ca.1 new file mode 100644 index 0000000..bccbbc4 --- /dev/null +++ b/secure/usr.bin/openssl/man/ca.1 @@ -0,0 +1,694 @@ +.\" Automatically generated by Pod::Man version 1.15 +.\" Sun Jan 12 18:04:59 2003 +.\" +.\" Standard preamble: +.\" ====================================================================== +.de Sh \" Subsection heading +.br +.if t .Sp +.ne 5 +.PP +\fB\\$1\fR +.PP +.. +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Ip \" List item +.br +.ie \\n(.$>=3 .ne \\$3 +.el .ne 3 +.IP "\\$1" \\$2 +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R + +.fi +.. +.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. 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\} +.el\{\ +. 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. +.if \nF \{\ +. 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. +.hy 0 +.if n .na +.\" +.\" 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 +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. 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 +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. 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 +.\} +.rm #[ #] #H #V #F C +.\" ====================================================================== +.\" +.IX Title "ca 3" +.TH ca 3 "0.9.7" "2003-01-12" "OpenSSL" +.UC +.SH "NAME" +ca \- sample minimal \s-1CA\s0 application +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +\&\fBopenssl\fR \fBca\fR +[\fB\-verbose\fR] +[\fB\-config filename\fR] +[\fB\-name section\fR] +[\fB\-gencrl\fR] +[\fB\-revoke file\fR] +[\fB\-crl_reason reason\fR] +[\fB\-crl_hold instruction\fR] +[\fB\-crl_compromise time\fR] +[\fB\-crl_CA_compromise time\fR] +[\fB\-subj arg\fR] +[\fB\-crldays days\fR] +[\fB\-crlhours hours\fR] +[\fB\-crlexts section\fR] +[\fB\-startdate date\fR] +[\fB\-enddate date\fR] +[\fB\-days arg\fR] +[\fB\-md arg\fR] +[\fB\-policy arg\fR] +[\fB\-keyfile arg\fR] +[\fB\-key arg\fR] +[\fB\-passin arg\fR] +[\fB\-cert file\fR] +[\fB\-in file\fR] +[\fB\-out file\fR] +[\fB\-notext\fR] +[\fB\-outdir dir\fR] +[\fB\-infiles\fR] +[\fB\-spkac file\fR] +[\fB\-ss_cert file\fR] +[\fB\-preserveDN\fR] +[\fB\-noemailDN\fR] +[\fB\-batch\fR] +[\fB\-msie_hack\fR] +[\fB\-extensions section\fR] +[\fB\-extfile section\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The \fBca\fR command is a minimal \s-1CA\s0 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. +.PP +The options descriptions will be divided into each purpose. +.SH "CA OPTIONS" +.IX Header "CA OPTIONS" +.Ip "\fB\-config filename\fR" 4 +.IX Item "-config filename" +specifies the configuration file to use. +.Ip "\fB\-name section\fR" 4 +.IX Item "-name section" +specifies the configuration file section to use (overrides +\&\fBdefault_ca\fR in the \fBca\fR section). +.Ip "\fB\-in filename\fR" 4 +.IX Item "-in filename" +an input filename containing a single certificate request to be +signed by the \s-1CA\s0. +.Ip "\fB\-ss_cert filename\fR" 4 +.IX Item "-ss_cert filename" +a single self signed certificate to be signed by the \s-1CA\s0. +.Ip "\fB\-spkac filename\fR" 4 +.IX Item "-spkac filename" +a file containing a single Netscape signed public key and challenge +and additional field values to be signed by the \s-1CA\s0. See the \fB\s-1SPKAC\s0 \s-1FORMAT\s0\fR +section for information on the required format. +.Ip "\fB\-infiles\fR" 4 +.IX Item "-infiles" +if present this should be the last option, all subsequent arguments +are assumed to the the names of files containing certificate requests. +.Ip "\fB\-out filename\fR" 4 +.IX Item "-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. +.Ip "\fB\-outdir directory\fR" 4 +.IX Item "-outdir directory" +the directory to output certificates to. The certificate will be +written to a filename consisting of the serial number in hex with +\&\*(L".pem\*(R" appended. +.Ip "\fB\-cert\fR" 4 +.IX Item "-cert" +the \s-1CA\s0 certificate file. +.Ip "\fB\-keyfile filename\fR" 4 +.IX Item "-keyfile filename" +the private key to sign requests with. +.Ip "\fB\-key password\fR" 4 +.IX Item "-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. +.Ip "\fB\-passin arg\fR" 4 +.IX Item "-passin arg" +the key password source. For more information about the format of \fBarg\fR +see the \fB\s-1PASS\s0 \s-1PHRASE\s0 \s-1ARGUMENTS\s0\fR section in openssl(1). +.Ip "\fB\-verbose\fR" 4 +.IX Item "-verbose" +this prints extra details about the operations being performed. +.Ip "\fB\-notext\fR" 4 +.IX Item "-notext" +don't output the text form of a certificate to the output file. +.Ip "\fB\-startdate date\fR" 4 +.IX Item "-startdate date" +this allows the start date to be explicitly set. The format of the +date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure). +.Ip "\fB\-enddate date\fR" 4 +.IX Item "-enddate date" +this allows the expiry date to be explicitly set. The format of the +date is \s-1YYMMDDHHMMSSZ\s0 (the same as an \s-1ASN1\s0 UTCTime structure). +.Ip "\fB\-days arg\fR" 4 +.IX Item "-days arg" +the number of days to certify the certificate for. +.Ip "\fB\-md alg\fR" 4 +.IX Item "-md alg" +the message digest to use. Possible values include md5, sha1 and mdc2. +This option also applies to CRLs. +.Ip "\fB\-policy arg\fR" 4 +.IX Item "-policy arg" +this option defines the \s-1CA\s0 \*(L"policy\*(R" to use. This is a section in +the configuration file which decides which fields should be mandatory +or match the \s-1CA\s0 certificate. Check out the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section +for more information. +.Ip "\fB\-msie_hack\fR" 4 +.IX Item "-msie_hack" +this is a legacy option to make \fBca\fR work with very old versions of +the \s-1IE\s0 certificate enrollment control \*(L"certenr3\*(R". It used UniversalStrings +for almost everything. Since the old control has various security bugs +its use is strongly discouraged. The newer control \*(L"Xenroll\*(R" does not +need this option. +.Ip "\fB\-preserveDN\fR" 4 +.IX Item "-preserveDN" +Normally the \s-1DN\s0 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 \s-1IE\s0 enrollment control which would only accept certificates if their +DNs match the order of the request. This is not needed for Xenroll. +.Ip "\fB\-noemailDN\fR" 4 +.IX Item "-noemailDN" +The \s-1DN\s0 of a certificate can contain the \s-1EMAIL\s0 field if present in the +request \s-1DN\s0, however it is good policy just having the e-mail set into +the altName extension of the certificate. When this option is set the +\&\s-1EMAIL\s0 field is removed from the certificate' subject and set only in +the, eventually present, extensions. The \fBemail_in_dn\fR keyword can be +used in the configuration file to enable this behaviour. +.Ip "\fB\-batch\fR" 4 +.IX Item "-batch" +this sets the batch mode. In this mode no questions will be asked +and all certificates will be certified automatically. +.Ip "\fB\-extensions section\fR" 4 +.IX Item "-extensions section" +the section of the configuration file containing certificate extensions +to be added when a certificate is issued (defaults to \fBx509_extensions\fR +unless the \fB\-extfile\fR option is used). 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. +.Ip "\fB\-extfile file\fR" 4 +.IX Item "-extfile file" +an additional configuration file to read certificate extensions from +(using the default section unless the \fB\-extensions\fR option is also +used). +.SH "CRL OPTIONS" +.IX Header "CRL OPTIONS" +.Ip "\fB\-gencrl\fR" 4 +.IX Item "-gencrl" +this option generates a \s-1CRL\s0 based on information in the index file. +.Ip "\fB\-crldays num\fR" 4 +.IX Item "-crldays num" +the number of days before the next \s-1CRL\s0 is due. That is the days from +now to place in the \s-1CRL\s0 nextUpdate field. +.Ip "\fB\-crlhours num\fR" 4 +.IX Item "-crlhours num" +the number of hours before the next \s-1CRL\s0 is due. +.Ip "\fB\-revoke filename\fR" 4 +.IX Item "-revoke filename" +a filename containing a certificate to revoke. +.Ip "\fB\-crl_reason reason\fR" 4 +.IX Item "-crl_reason reason" +revocation reason, where \fBreason\fR is one of: \fBunspecified\fR, \fBkeyCompromise\fR, +\&\fBCACompromise\fR, \fBaffiliationChanged\fR, \fBsuperseded\fR, \fBcessationOfOperation\fR, +\&\fBcertificateHold\fR or \fBremoveFromCRL\fR. The matching of \fBreason\fR is case +insensitive. Setting any revocation reason will make the \s-1CRL\s0 v2. +.Sp +In practive \fBremoveFromCRL\fR is not particularly useful because it is only used +in delta CRLs which are not currently implemented. +.Ip "\fB\-crl_hold instruction\fR" 4 +.IX Item "-crl_hold instruction" +This sets the \s-1CRL\s0 revocation reason code to \fBcertificateHold\fR and the hold +instruction to \fBinstruction\fR which must be an \s-1OID\s0. Although any \s-1OID\s0 can be +used only \fBholdInstructionNone\fR (the use of which is discouraged by \s-1RFC2459\s0) +\&\fBholdInstructionCallIssuer\fR or \fBholdInstructionReject\fR will normally be used. +.Ip "\fB\-crl_compromise time\fR" 4 +.IX Item "-crl_compromise time" +This sets the revocation reason to \fBkeyCompromise\fR and the compromise time to +\&\fBtime\fR. \fBtime\fR should be in GeneralizedTime format that is \fB\s-1YYYYMMDDHHMMSSZ\s0\fR. +.Ip "\fB\-crl_CA_compromise time\fR" 4 +.IX Item "-crl_CA_compromise time" +This is the same as \fBcrl_compromise\fR except the revocation reason is set to +\&\fBCACompromise\fR. +.Ip "\fB\-subj arg\fR" 4 +.IX Item "-subj arg" +supersedes subject name given in the request. +The arg must be formatted as \fI/type0=value0/type1=value1/type2=...\fR, +characters may be escaped by \e (backslash), no spaces are skipped. +.Ip "\fB\-crlexts section\fR" 4 +.IX Item "-crlexts section" +the section of the configuration file containing \s-1CRL\s0 extensions to +include. If no \s-1CRL\s0 extension section is present then a V1 \s-1CRL\s0 is +created, if the \s-1CRL\s0 extension section is present (even if it is +empty) then a V2 \s-1CRL\s0 is created. The \s-1CRL\s0 extensions specified are +\&\s-1CRL\s0 extensions and \fBnot\fR \s-1CRL\s0 entry extensions. It should be noted +that some software (for example Netscape) can't handle V2 CRLs. +.SH "CONFIGURATION FILE OPTIONS" +.IX Header "CONFIGURATION FILE OPTIONS" +The section of the configuration file containing options for \fBca\fR +is found as follows: If the \fB\-name\fR command line option is used, +then it names the section to be used. Otherwise the section to +be used must be named in the \fBdefault_ca\fR option of the \fBca\fR section +of the configuration file (or in the default section of the +configuration file). Besides \fBdefault_ca\fR, the following options are +read directly from the \fBca\fR section: + \s-1RANDFILE\s0 + preserve + msie_hack +With the exception of \fB\s-1RANDFILE\s0\fR, this is probably a bug and may +change in future releases. +.PP +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. +.Ip "\fBoid_file\fR" 4 +.IX Item "oid_file" +This specifies a file containing additional \fB\s-1OBJECT\s0 \s-1IDENTIFIERS\s0\fR. +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. +.Ip "\fBoid_section\fR" 4 +.IX 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 \fB=\fR and the numerical form. The short +and long names are the same when this option is used. +.Ip "\fBnew_certs_dir\fR" 4 +.IX Item "new_certs_dir" +the same as the \fB\-outdir\fR command line option. It specifies +the directory where new certificates will be placed. Mandatory. +.Ip "\fBcertificate\fR" 4 +.IX Item "certificate" +the same as \fB\-cert\fR. It gives the file containing the \s-1CA\s0 +certificate. Mandatory. +.Ip "\fBprivate_key\fR" 4 +.IX Item "private_key" +same as the \fB\-keyfile\fR option. The file containing the +\&\s-1CA\s0 private key. Mandatory. +.Ip "\fB\s-1RANDFILE\s0\fR" 4 +.IX Item "RANDFILE" +a file used to read and write random number seed information, or +an \s-1EGD\s0 socket (see RAND_egd(3)). +.Ip "\fBdefault_days\fR" 4 +.IX Item "default_days" +the same as the \fB\-days\fR option. The number of days to certify +a certificate for. +.Ip "\fBdefault_startdate\fR" 4 +.IX Item "default_startdate" +the same as the \fB\-startdate\fR option. The start date to certify +a certificate for. If not set the current time is used. +.Ip "\fBdefault_enddate\fR" 4 +.IX Item "default_enddate" +the same as the \fB\-enddate\fR option. Either this option or +\&\fBdefault_days\fR (or the command line equivalents) must be +present. +.Ip "\fBdefault_crl_hours default_crl_days\fR" 4 +.IX Item "default_crl_hours default_crl_days" +the same as the \fB\-crlhours\fR and the \fB\-crldays\fR 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. +.Ip "\fBdefault_md\fR" 4 +.IX Item "default_md" +the same as the \fB\-md\fR option. The message digest to use. Mandatory. +.Ip "\fBdatabase\fR" 4 +.IX Item "database" +the text database file to use. Mandatory. This file must be present +though initially it will be empty. +.Ip "\fBserialfile\fR" 4 +.IX 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. +.Ip "\fBx509_extensions\fR" 4 +.IX Item "x509_extensions" +the same as \fB\-extensions\fR. +.Ip "\fBcrl_extensions\fR" 4 +.IX Item "crl_extensions" +the same as \fB\-crlexts\fR. +.Ip "\fBpreserve\fR" 4 +.IX Item "preserve" +the same as \fB\-preserveDN\fR +.Ip "\fBemail_in_dn\fR" 4 +.IX Item "email_in_dn" +the same as \fB\-noemailDN\fR. 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. +.Ip "\fBmsie_hack\fR" 4 +.IX Item "msie_hack" +the same as \fB\-msie_hack\fR +.Ip "\fBpolicy\fR" 4 +.IX Item "policy" +the same as \fB\-policy\fR. Mandatory. See the \fB\s-1POLICY\s0 \s-1FORMAT\s0\fR section +for more information. +.Ip "\fBnameopt\fR, \fBcertopt\fR" 4 +.IX 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 \fBx509\fR utilities \fB\-nameopt\fR and \fB\-certopt\fR switches can be used +here, except the \fBno_signame\fR and \fBno_sigdump\fR 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 \fBdefault_ca\fR 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 \fBstrongly\fR discouraged because +it only displays fields mentioned in the \fBpolicy\fR section, mishandles +multicharacter string types and does not display extensions. +.Ip "\fBcopy_extensions\fR" 4 +.IX Item "copy_extensions" +determines how extensions in certificate requests should be handled. +If set to \fBnone\fR or this option is not present then extensions are +ignored and not copied to the certificate. If set to \fBcopy\fR then any +extensions present in the request that are not already present are copied +to the certificate. If set to \fBcopyall\fR 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 \fB\s-1WARNINGS\s0\fR 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. +.SH "POLICY FORMAT" +.IX Header "POLICY FORMAT" +The policy section consists of a set of variables corresponding to +certificate \s-1DN\s0 fields. If the value is \*(L"match\*(R" then the field value +must match the same field in the \s-1CA\s0 certificate. If the value is +\&\*(L"supplied\*(R" then it must be present. If the value is \*(L"optional\*(R" then +it may be present. Any fields not mentioned in the policy section +are silently deleted, unless the \fB\-preserveDN\fR option is set but +this can be regarded more of a quirk than intended behaviour. +.SH "SPKAC FORMAT" +.IX Header "SPKAC FORMAT" +The input to the \fB\-spkac\fR command line option is a Netscape +signed public key and challenge. This will usually come from +the \fB\s-1KEYGEN\s0\fR tag in an \s-1HTML\s0 form to create a new private key. +It is however possible to create SPKACs using the \fBspkac\fR utility. +.PP +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 '.'. +.SH "EXAMPLES" +.IX Header "EXAMPLES" +Note: these examples assume that the \fBca\fR directory structure is +already set up and the relevant files already exist. This usually +involves creating a \s-1CA\s0 certificate and private key with \fBreq\fR, a +serial number file and an empty index file and placing them in +the relevant directories. +.PP +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. +.PP +Sign a certificate request: +.PP +.Vb 1 +\& openssl ca -in req.pem -out newcert.pem +.Ve +Sign a certificate request, using \s-1CA\s0 extensions: +.PP +.Vb 1 +\& openssl ca -in req.pem -extensions v3_ca -out newcert.pem +.Ve +Generate a \s-1CRL\s0 +.PP +.Vb 1 +\& openssl ca -gencrl -out crl.pem +.Ve +Sign several requests: +.PP +.Vb 1 +\& openssl ca -infiles req1.pem req2.pem req3.pem +.Ve +Certify a Netscape \s-1SPKAC:\s0 +.PP +.Vb 1 +\& openssl ca -spkac spkac.txt +.Ve +A sample \s-1SPKAC\s0 file (the \s-1SPKAC\s0 line has been truncated for clarity): +.PP +.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 \fBca\fR: +.PP +.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 +.SH "FILES" +.IX Header "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. +.PP +.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 +.SH "ENVIRONMENT VARIABLES" +.IX Header "ENVIRONMENT VARIABLES" +\&\fB\s-1OPENSSL_CONF\s0\fR reflects the location of master configuration file it can +be overridden by the \fB\-config\fR command line option. +.SH "RESTRICTIONS" +.IX Header "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 +\&\s-1CRL:\s0 however there is no option to do this. +.PP +V2 \s-1CRL\s0 features like delta \s-1CRL\s0 support and \s-1CRL\s0 numbers are not currently +supported. +.PP +Although several requests can be input and handled at once it is only +possible to include one \s-1SPKAC\s0 or self signed certificate. +.SH "BUGS" +.IX Header "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. +.PP +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. +.PP +The \fBca\fR 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 \fB\s-1CA\s0.sh\fR and +\&\fB\s-1CA\s0.pl\fR help a little but not very much. +.PP +Any fields in a request that are not present in a policy are silently +deleted. This does not happen if the \fB\-preserveDN\fR 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 \fB\-noemailDN\fR +option can be used. The behaviour should be more friendly and +configurable. +.PP +Cancelling some commands by refusing to certify a certificate can +create an empty file. +.SH "WARNINGS" +.IX Header "WARNINGS" +The \fBca\fR command is quirky and at times downright unfriendly. +.PP +The \fBca\fR 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. +.PP +The \fBca\fR command is effectively a single user command: no locking is +done on the various files and attempts to run more than one \fBca\fR command +on the same database can have unpredictable results. +.PP +The \fBcopy_extensions\fR 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\fR value is set to \fBcopyall\fR and the user does not spot +this when the certificate is displayed then this will hand the requestor +a valid \s-1CA\s0 certificate. +.PP +This situation can be avoided by setting \fBcopy_extensions\fR to \fBcopy\fR +and including basicConstraints with \s-1CA:FALSE\s0 in the configuration file. +Then if the request contains a basicConstraints extension it will be +ignored. +.PP +It is advisable to also include values for other extensions such +as \fBkeyUsage\fR to prevent a request supplying its own values. +.PP +Additional restrictions can be placed on the \s-1CA\s0 certificate itself. +For example if the \s-1CA\s0 certificate has: +.PP +.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. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +req(1), spkac(1), x509(1), CA.pl(1), +config(5) -- cgit v1.1