diff options
Diffstat (limited to 'secure/usr.bin/openssl/man/ca.1')
| -rw-r--r-- | secure/usr.bin/openssl/man/ca.1 | 758 |
1 files changed, 758 insertions, 0 deletions
diff --git a/secure/usr.bin/openssl/man/ca.1 b/secure/usr.bin/openssl/man/ca.1 new file mode 100644 index 0000000..b22ed99 --- /dev/null +++ b/secure/usr.bin/openssl/man/ca.1 @@ -0,0 +1,758 @@ +.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.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. \*(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- +.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" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is turned on, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{ +. if \nF \{ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" 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 1" +.TH CA 1 "2016-03-01" "1.0.2g" "OpenSSL" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +ca \- sample minimal CA 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\-status serial\fR] +[\fB\-updatedb\fR] +[\fB\-crl_reason reason\fR] +[\fB\-crl_hold instruction\fR] +[\fB\-crl_compromise time\fR] +[\fB\-crl_CA_compromise time\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\-keyform PEM|DER\fR] +[\fB\-key arg\fR] +[\fB\-passin arg\fR] +[\fB\-cert file\fR] +[\fB\-selfsign\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] +[\fB\-engine id\fR] +[\fB\-subj arg\fR] +[\fB\-utf8\fR] +[\fB\-multivalue\-rdn\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 FORMAT\s0\fR +section for information on the required input and output format. +.IP "\fB\-infiles\fR" 4 +.IX Item "-infiles" +if present this should be the last option, all subsequent arguments +are assumed to be 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 in \s-1PEM\s0 format (except that \fB\-spkac\fR outputs \s-1DER\s0 format). +.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\-keyform PEM|DER\fR" 4 +.IX Item "-keyform PEM|DER" +the format of the data in the private key file. +The default is \s-1PEM.\s0 +.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\-selfsign\fR" 4 +.IX Item "-selfsign" +indicates the issued certificates are to be signed with the key +the certificate requests were signed with (given with \fB\-keyfile\fR). +Cerificate requests signed with a different key are ignored. If +\&\fB\-spkac\fR, \fB\-ss_cert\fR or \fB\-gencrl\fR are given, \fB\-selfsign\fR is +ignored. +.Sp +A consequence of using \fB\-selfsign\fR is that the self-signed +certificate appears among the entries in the certificate database +(see the configuration option \fBdatabase\fR), and uses the same +serial number counter as all other certificates sign with the +self-signed certificate. +.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 PHRASE ARGUMENTS\s0\fR section in \fIopenssl\fR\|(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 FORMAT\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. See the:w +\&\fIx509v3_config\fR\|(5) manual page for details of the +extension section format. +.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). +.IP "\fB\-engine id\fR" 4 +.IX Item "-engine id" +specifying an engine (by its unique \fBid\fR string) will cause \fBca\fR +to attempt to obtain a functional reference to the specified engine, +thus initialising it if needed. The engine will then be set as the default +for all available algorithms. +.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\-utf8\fR" 4 +.IX Item "-utf8" +this option causes field values to be interpreted as \s-1UTF8\s0 strings, by +default they are interpreted as \s-1ASCII.\s0 This means that the field +values, whether prompted from a terminal or obtained from a +configuration file, must be valid \s-1UTF8\s0 strings. +.IP "\fB\-multivalue\-rdn\fR" 4 +.IX Item "-multivalue-rdn" +this option causes the \-subj argument to be interpretedt with full +support for multivalued RDNs. Example: +.Sp +\&\fI/DC=org/DC=OpenSSL/DC=users/UID=123456+CN=John Doe\fR +.Sp +If \-multi\-rdn is not used then the \s-1UID\s0 value is \fI123456+CN=John Doe\fR. +.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\-status serial\fR" 4 +.IX Item "-status serial" +displays the revocation status of the certificate with the specified +serial number and exits. +.IP "\fB\-updatedb\fR" 4 +.IX Item "-updatedb" +Updates the database index to purge expired certificates. +.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\-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. See +\&\fIx509v3_config\fR\|(5) manual page for details of the +extension section format. +.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 IDENTIFIERS\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 \fIRAND_egd\fR\|(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 "\fBunique_subject\fR" 4 +.IX Item "unique_subject" +if the value \fByes\fR is given, the valid certificate entries in the +database must have unique subjects. if the value \fBno\fR is given, +several valid certificate entries may have the exact same subject. +The default value is \fByes\fR, to be compatible with older (pre 0.9.8) +versions of OpenSSL. However, to make \s-1CA\s0 certificate roll-over easier, +it's recommended to use the value \fBno\fR, especially if combined with +the \fB\-selfsign\fR command line option. +.IP "\fBserial\fR" 4 +.IX Item "serial" +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 "\fBcrlnumber\fR" 4 +.IX Item "crlnumber" +a text file containing the next \s-1CRL\s0 number to use in hex. The crl number +will be inserted in the CRLs only if this file exists. If this file is +present, it must contain a valid \s-1CRL\s0 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 FORMAT\s0\fR section +for more information. +.IP "\fBname_opt\fR, \fBcert_opt\fR" 4 +.IX Item "name_opt, cert_opt" +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 \fBca_default\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 '.'. +.PP +When processing \s-1SPKAC\s0 format, the output is \s-1DER\s0 if the \fB\-out\fR +flag is used, but \s-1PEM\s0 format if sending to stdout or the \fB\-outdir\fR +flag is used. +.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 +.PP +Sign a certificate request, using \s-1CA\s0 extensions: +.PP +.Vb 1 +\& openssl ca \-in req.pem \-extensions v3_ca \-out newcert.pem +.Ve +.PP +Generate a \s-1CRL\s0 +.PP +.Vb 1 +\& openssl ca \-gencrl \-out crl.pem +.Ve +.PP +Sign several requests: +.PP +.Vb 1 +\& openssl ca \-infiles req1.pem req2.pem req3.pem +.Ve +.PP +Certify a Netscape \s-1SPKAC:\s0 +.PP +.Vb 1 +\& openssl ca \-spkac spkac.txt +.Ve +.PP +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 +.PP +A sample configuration file with the relevant sections for \fBca\fR: +.PP +.Vb 2 +\& [ 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 +\& email_in_dn = no # Don\*(Aqt add the email into cert DN +\& +\& name_opt = ca_default # Subject name display option +\& cert_opt = ca_default # Certificate display option +\& copy_extensions = none # Don\*(Aqt copy extensions from request +\& +\& [ 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 CRLs 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 +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 +.PP +then even if a certificate is issued with \s-1CA:TRUE\s0 it will not be valid. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fIreq\fR\|(1), \fIspkac\fR\|(1), \fIx509\fR\|(1), \s-1\fICA\s0.pl\fR\|(1), +\&\fIconfig\fR\|(5), \fIx509v3_config\fR\|(5) |
