CA(1) OpenSSL CA(1)
NAME
ca - sample minimal CA
application
# 注释 ：ca 是简单的 mini CA 工具
SYNOPSIS
openssl ca
[-verbose] [-config filename] [-name section] [-gencrl]
[-revoke file] [-crl_reason reason] [-crl_hold instruction]
[-crl_com-
promise time] [-crl_CA_compromise time] [-subj arg] [-crldays days] [-crlhours
hours] [-crlexts section] [-startdate date] [-enddate
date]
[-days arg] [-md arg] [-policy arg]
[-keyfile arg] [-key arg] [-passin arg] [-cert file]
[-in file] [-out file] [-notext] [-outdir dir]
[-infiles]
[-spkac file] [-ss_cert file] [-preserveDN] [-noemailDN] [-batch]
[-msie_hack] [-extensions section] [-extfile
section]
[-engine id]
DESCRIPTION
The 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.
# 注释 ：ca 子命令是一个小型 CA 。它可以
用于对证书请求进行签名（以不同的格式），并生成 CRL 列表，
# 它同时还维护一个文本数据库，记录了所有它颁发的证书以及它们的状态
The options descriptions will be divided into each purpose.
# 注释 ：下面按选项的用途分别进行介绍
CA OPTIONS
-config filename
specifies the configuration
file to use.
# 注释 ：-config 指定配置文件
-name section
specifies the configuration
file section to use (overrides
default_ca in the ca section).
# 注释 ：-name 指定要使用配置文件中那个 section ，默认是 [
default_ca ] 部分
-in filename
an input filename containing a
single certificate request to be
signed by the CA.
# 注释 ：-in 指定一个 CSR 文件，用于被该 CA 签名
-ss_cert filename
a single self signed
certificate to be signed by the CA.
# 注释 ：-ssl_cert 指定一个自签名的证书，要被 CA
签名
-spkac filename
a file containing a single
Netscape signed public key and chal-
lenge and additional field values to
be signed by the CA. See the
SPKAC FORMAT section for information on the
required format.
-infiles
if present this should be the last
option, all subsequent argu-
ments are assumed to the the names of files
containing certificate
requests.
# 注释 ：-infiles 如果被指定，必须是最后一个，它表示后面的都是要签名的 CSR
文件名
-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.
# 注释 ：-out 指定输出文件名
-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.
# 注释 ：-outdir 设置输出证书的目录。证书的文件名是
<16进制序列号>.pem
# 默认是 demoCA/newcerts/
-cert
the CA certificate file.
# 注释 ：-cert 表示该 CA 的证书文件
-keyfile filename
the private key to sign
requests with.
# 注释 ：-keyfile 指定 CA 的 private key
-key password
the password used to encrypt
the private key. Since on some sys-
tems the command line arguments are
visible (e.g. Unix with the
’ps’ utility) this option should be used with
caution.
# 注释 ：-key 指定 private key
的口令句，是用于输出密钥的加密的
-passin arg
the key password source. For
more information about the format of
arg see the PASS PHRASE ARGUMENTS
section in openssl(1).
# 注释 ：-passin 指定输入的 CA 私钥的口令句
-verbose
this prints extra details about the
operations being performed.
# 注释 ：-verbose 是冗余模式
-notext
don’t output the text form of a
certificate to the output file.
# 注释 ：-notext 不输出一个证书的文本部分
-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).
# 注释 ：-startdate 允许设置证书的启用时间
-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).
# 注释 ：-enddate 允许设置证书的过期时间
-days arg
the number of days to certify the
certificate for.
# 注释 ：-days 指定证书的有效期。
-md alg
the message digest to use. Possible
values include md5, sha1 and
mdc2. This option also applies to
CRLs.
# 注释 ：-md 指定消息摘要的算法，可以有
md5、sha1、mdc2
-policy arg
this option defines the CA
"policy" to use. This is a section in
the configuration file which
decides which fields should be manda-
tory or match the CA certificate.
Check out the POLICY FORMAT sec-
tion for more information.
# 注释 ：-policy 指定 CA 的策略。它定义了那个字段是必须的，那个字段必须匹配
CA 的证书
# 具体在配置文件中 ：
# A few difference way of
specifying how similar the request should look
# For type CA, the listed
attributes must be the same, and the optional
# and supplied fields are just
that :-)
policy = policy_match
# For the CA policy
[
policy_match ]
countryName = match
stateOrProvinceName =
match
organizationName = match
organizationalUnitName =
optional
commonName = supplied
emailAddress =
optional
# For the 'anything' policy
# At
this point in time, you must list all acceptable 'object'
# types.
[
policy_anything ]
countryName =
optional
stateOrProvinceName = optional
localityName =
optional
organizationName = optional
organizationalUnitName =
optional
commonName = supplied
emailAddress =
optional
-msie_hack
this is a legacy option to make
ca work with very old versions of
the IE certificate enrollment control
"certenr3". It used Univer-
salStrings for almost everything. Since the
old control has vari-
ous security bugs its use is strongly discouraged.
The newer con-
trol "Xenroll" does not need this option.
-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 compati-
bility 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.
-noemailDN
The DN of a certificate can
contain the EMAIL field if present in
the request DN, however it is good
policy just having the e-mail
set into the altName extension of the
certificate. When this
option is set the EMAIL field is removed from the
certificate’
subject and set only in the, eventually present, extensions.
The
email_in_dn keyword can be used in the configuration file to
enable this behaviour.
-batch
this sets the batch mode. In this
mode no questions will be asked
and all certificates will be certified
automatically.
# 注释 ：-batch 下不会询问任何问题，所有证书会被自动认证。
-extensions section
the section of the
configuration file containing certificate
extensions to be added when a
certificate is issued (defaults to
x509_extensions unless the -extfile
option is used). If no exten-
sion section is present then, a V1
certificate is created. If the
extension section is present (even if it
is empty), then a V3 cer-
tificate is created.
# 注释 ：-extensions
设置当一个也证书被发出时，要在证书的尾部添加什么证书扩展信息。
# 默认是配置文件中的 [ x509_extenssions ] 。如果没有
extensions 部分存在，则一个 V1
# 证书被建立，如果 extensions 部分不能从，则建立一个 v3
证书
# To use this configuration file
with the "-extfile" option of the
# "openssl x509" utility, name here the
section containing the
# X.509v3 extensions to use:
#
extensions =
# (Alternatively, use a configuration file that has
only
# X.509v3 extensions in its main [= default] section.)
[ req ]
default_bits
= 1024
#default_keyfile = privkey.pem
default_keyfile =
my_default_private.pem
distinguished_name =
req_distinguished_name
attributes = req_attributes
x509_extensions = v3_ca # The extentions to add to the self signed
cert
[ v3_ca
]
# Extensions for a typical
CA
# PKIX
recommendation.
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid:always,issuer:always
# This is what PKIX recommends but
some broken software chokes on critical
# extensions.
#basicConstraints =
critical,CA:true
# So we do this instead.
basicConstraints =
CA:true
# Key usage: this is typical for a
CA certificate. However since it will
# prevent it being used as an test
self-signed certificate it is best
# left out by default.
# keyUsage =
cRLSign, keyCertSign
# Some might want this also
#
nsCertType = sslCA, emailCA
# Include email address in subject
alt name: another PKIX recommendation
# subjectAltName=email:copy
# Copy
issuer details
# issuerAltName=issuer:copy
# DER hex encoding of an extension:
beware experts only!
# obj=DER:02:03
# Where 'obj' is a standard or added
object
# You can even override a supported extension:
# basicConstraints=
critical, DER:30:03:01:01:FF
-extfile file
an additional configuration
file to read certificate extensions
from (using the default section
unless the -extensions option is
also used).
# 注释 ：-extfile
指定一个额外配置文件用于读取证书扩展信息。
-engine id
specifying an engine (by it’s unique id string)
will cause req 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.
CRL OPTIONS
-gencrl
this option generates a CRL based on information in the index file.
# 注释 ：-gencrl 用于生成一个 CRL 信息，依据是 index 文件。该文件是
CA 脚本的 -newca 选项生成的
-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.
# 注释 ：-crldays 用于设置下一个 CRL 被生成的时间。也就是多久更新一次 CRL
# 该值会被放在 CRL 的 nextUpdate 字段中。
-crlhours num
the number of hours before the
next CRL is due.
# 注释 ：-crlhours 表示多时小时候更新 CRL
-revoke filename
a filename containing a
certificate to revoke.
# 注释 ：-revoke 用于收回一个证书
-crl_reason reason
revocation reason, where
reason is one of: unspecified, keyCompro-
mise, CACompromise,
affiliationChanged, superseded, cessationOfOp-
eration, certificateHold
or removeFromCRL. The matching of reason
is case insensitive. Setting any
revocation reason will make the
CRL v2.
# 注释 ：-crl_reason 用于指定回收的原因，可以是 ：
# -）1、unspecified
# -）2、keyCompromise
# -）3、CACompromise
# -）4、affiliationChanged
# -）5、superseded
# -）6、cessationOfOperation
# -）7、certificateHold
# -）8、removeFromCRL
# 要注意，上述的原因是不区分大小写的。只要设置了该选项，就会生成一个 V2 版本的
CRL
In practive removeFromCRL is not particularly useful because it
is
only used in delta CRLs which are not currently implemented.
# 注释 ：removeFromCRL 这个原因不太有效，目前未实现
-crl_hold instruction
This sets the CRL
revocation reason code to certificateHold and
the hold instruction to
instruction which must be an OID. Although
any OID can be used only
holdInstructionNone (the use of which is
discouraged by RFC2459)
holdInstructionCallIssuer or holdInstruc-
tionReject will normally be
used.
# 注释 ：-crl_hold
-crl_compromise time
This sets the
revocation reason to keyCompromise and the compro-
mise time to time.
time should be in GeneralizedTime format that
is YYYYMMDDHHMMSSZ.
# 注释 ：-crl_comromise 用于设置回收的原因为 keyCompromise
，并设置 private key 信息泄露的时间
# 时间的格式是 YYYYMMDDHHMMSSZ
-crl_CA_compromise time
This is the same as
crl_compromise except the revocation reason is
set to CACompromise.
# 注释 ：-crl_CA_compromise
同上，只不过原因不同而已
-subj arg
supersedes subject name given in
the request. The arg must be
formatted as
/type0=value0/type1=value1/type2=..., characters may
be escaped by \
(backslash), no spaces are skipped.
# 注释 ：-subj 用于替换 CSR 中的 subject
字段的内容
-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 not CRL
entry extensions. It should be noted
that some software (for example
Netscape) can’t handle V2 CRLs.
# 注释 ：-crlexts 用于设置 CRL 的扩展信息。
# 补充 ：在配置文件中关于 CRL 的信息有
crl_dir =
$dir/crl # Where the issued crl are kept
crl =
$dir/crl.pem # The current CRL
# Extensions to add to a CRL. Note:
Netscape communicator chokes on V2 CRLs
# so this is commented out by default
to leave a V1 CRL.
# crl_extensions = crl_ext
default_crl_days=
30 # how long before next CRL
[ crl_ext ]
# CRL extensions.
# Only
issuerAltName and authorityKeyIdentifier make any sense in a CRL.
#
issuerAltName=issuer:copy
authorityKeyIdentifier=keyid:always,issuer:always
CONFIGURATION FILE OPTIONS
The section of the configuration file containing options for ca is
found as follows: If the -name command line option is used, then it
names the section to be used. Otherwise the section to be used must be
named in the default_ca option of the ca section of the configuration
file (or in the default section of the configuration file). Besides
default_ca, the following options are read directly from the ca sec-
tion:
RANDFILE
preserve
msie_hack With the exception of RANDFILE,
this is probably a bug and
may change in future releases.
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.
oid_file
This specifies a file containing
additional 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 fol-
lowed by white space and finally the long name.
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.
new_certs_dir
the same as the -outdir
command line option. It specifies the
directory where new certificates
will be placed. Mandatory.
certificate
the same as -cert. It gives the
file containing the CA certifi-
cate. Mandatory.
private_key
same as the -keyfile option. The
file containing the CA private
key. Mandatory.
RANDFILE
a file used to read and write
random number seed information, or
an EGD socket (see RAND_egd(3)).
default_days
the same as the -days option. The number of days to certify a
cer-
tificate for.
default_startdate
the same as the -startdate
option. The start date to certify a
certificate for. If not set the
current time is used.
default_enddate
the same as the -enddate
option. Either this option or
default_days (or the command line
equivalents) must be present.
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 CRL.
default_md
the same as the -md option. The
message digest to use. Mandatory.
database
the text database file to use.
Mandatory. This file must be
present though initially it will be
empty.
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.
x509_extensions
the same as
-extensions.
crl_extensions
the same as -crlexts.
preserve
the same as -preserveDN
email_in_dn
the same as -noemailDN. If you
want the EMAIL field to be removed
from the DN of the certificate simply
set this to ’no’. If not
present the default is to allow for the EMAIL
filed in the cer-
tificate’s DN.
msie_hack
the same as -msie_hack
policy
the same as -policy. Mandatory. See
the POLICY FORMAT section for
more information.
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 signa-
ture cannot be displayed because the certificate
has not been
signed at this point).
For convenience the values default_ca are accepted by both to
pro-
duce a reasonable output.
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 exten-
sions.
copy_extensions
determines how extensions in
certificate requests should be han-
dled. If set to none or this option
is not present then exten-
sions 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 WARNINGS section before using this
option.
The main use of this option is to allow a certificate request to
supply values for certain extensions such as subjectAltName.
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 "sup-
plied" 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 -preserveDN option is set but this can be
regarded more of
a quirk than intended behaviour.
# 注释 ：如果某个的字段的值是 match ，则必须匹配 CA 证书对应字段的值
# 如果是 supplied ，则该字段的值必须存在。
# 如果是 optional 则该字段的值可以为空
# 任何不在 policy 部分的字段都会被删除，除非使用了 -preserverDN
SPKAC FORMAT
The input to
the -spkac command line option is a Netscape signed pub-
lic key and
challenge. This will usually come from the KEYGEN tag in
an HTML form
to create a new private key. It is however possible to
create SPKACs
using the 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 ’.’.
EXAMPLES
Note: these
examples assume that the ca directory structure is already
set up and
the relevant files already exist. This usually involves
creating a CA
certificate and private key with req, a serial number
file and an
empty index file and placing them in the relevant directo-
ries.
# 注释 ：注意！下面的命令是假设已经存在一个 ca 结构目录了，并且相关的文件也存在（执行过
CA 脚本了）
# 实际上就是建立一些目录，然后把 CA 自己的证书、CA 自己的私钥、序列号文件、index
文件拷贝到相应的地方
To use the sample configuration file below the directories
demoCA,
demoCA/private and demoCA/newcerts would be created. The CA
certifi-
cate would be copied to demoCA/cacert.pem and its private key
to
demoCA/private/cakey.pem. A file demoCA/serial would be created
con-
taining for example "01" and the empty index file
demoCA/index.txt.
# 注释 ：目录结构为 ：
./demoCA , ./demoCA/private ， ./demoCA/newcerts
# CA 的证书放在 demoCA/cacert.pem ，私钥文件放在
demoCA/private/cakey.pem 。
# 序列号文件 serial 放在 demoCA/ 下，值从 01
开始。
# 序列号文件 index.txt 放在 demoCA/ 下
Sign a certificate request:
# 注释 ：下面的命令对一个 CSR 进行签名
openssl ca -in req.pem -out newcert.pem
Sign a certificate request, using CA extensions:
# 注释 ：下面的命令对一个 CSR 签名，同时使用 CA 扩展，为配置文件中的 v3_ca
部分
openssl ca -in req.pem -extensions v3_ca -out
newcert.pem
Generate a CRL
# 注释 ：下面的命令生成一个 CRL 文件（PEM 格式）
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
0.OU=OpenSSL
Group
1.OU=Another Group
A sample configuration file with the relevant sections for 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
email_in_dn =
no # Don’t add the email into cert DN
nameopt = default_ca # Subject name display
option
certopt = default_ca # Certificate display
option
copy_extensions = none # Don’t copy extensions from
request
[ policy_any ]
countryName =
supplied
stateOrProvinceName = optional
organizationName =
optional
organizationalUnitName = optional
commonName =
supplied
emailAddress = optional
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
ENVIRONMENT VARIABLES
OPENSSL_CONF reflects the location of master configuration file it can
be overridden by the -config command line option.
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.
V2 CRL features like delta CRL support and CRL numbers are not
cur-
rently supported.
Although several requests can be input and handled at once it is
only
possible to include one SPKAC or self signed certificate.
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.
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 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
CA.sh and 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 -preserveDN option is
used. To
enforce the absence of the EMAIL field within the DN, as
suggested by
RFCs, regardless the contents of the request’ subject the
-noemailDN
option can be used. The behaviour should be more friendly
and config-
urable.
Cancelling some commands by refusing to certify a certificate can
cre-
ate an empty file.
WARNINGS
The ca command is quirky and at times downright
unfriendly.
The ca utility was originally meant as an example of how to do
things
in a CA. It was not supposed to be used as a full blown CA
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 CA:TRUE
and the
copy_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 CA certificate.
This situation can be avoided by setting copy_extensions to copy
and
including basicConstraints with CA:FALSE 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 CA certificate
itself.
For example if the CA certificate has:
basicConstraints = CA:TRUE, pathlen:0
then even if a certificate is issued with CA:TRUE it will not
be
valid.
SEE ALSO
req(1), spkac(1), x509(1), CA.pl(1), config(5)
0.9.7a 2003-01-30 CA(1)
