instructions

simpleca 比起正式的CA来说功能简单

                         SimpleCA Instructions

SimpleCA is an easy-to-use program that gives a typical sysadmin who
needs to create certificates an easy interface. It has fewer features
and options than many CA packages. It allows all options on the
command-line and in a config file, and comes with a default config file
that has (hopefully) sensible defaults so that the sysadmin can start
writing certs without knowing much.


1. Installing SimpleCA

SimpleCA comes both pre-compiled and as source code. In its pre-compiled
version for Unix-like systems, it is an executable called "simpleca-type",
such as "simpleca-linux". For Windows, it is called "simpleca.exe"; you must
also have the file "cl32.dll" in the same directory as "simpleca.exe". In
this document, the program name is just shown as "simpleca". For information
on how to build SimpleCA from source code, see the file in the distribution
called "Building".


2. SimpleCA Basics

SimpleCA is a command-line program: it has no graphical user interface.
You run the program each time you want to start a certificate authority,
to issue a certificate, to view a certificate request, or to view
an already-issued certificate.

2.1 Specifying options

The options are almost all in the form option=value. There are no
leading hyphens on the option names. A typical command line might be:

	simpleca create-cert=thecert.out subj-alt=dnsname:example.com

Most options take arguments of filenames, directory names, strings, or
dates. Some options take no values.

- Filenames are OS-specific; the string "STDOUT" can be used to indicate the
standard output stream.

- Strings are assumed to be in UTF-8.

- Dates are strings and can be given as either YYYYMMDDHHMMSSZ or
nnn{h|d|m|y}. For instance "5d" means five days from now.

SimpleCA has some restrictions on the data entered that are based on
restrictions on cryplib, the underlying toolking SimpleCA relies on.
For example, email addresses must be eight characters long, and
passwords must be at least two characters long.

2.2 Config files and command lines

SimpleCA allows any option to be put either on the command line or in
config files. Values of options are overwritten if there are multiple
instances of the option.

It is possible to invoke more than one config file by having more than
one "config" option on the command line or in a config file. The options
are processed in order, starting with the default config file, then
followed by the command line. Config files are read from top to bottom;
command lines from left to right.

Command line options are just like config file options except:

- command lines need OS-specific quoting

- new lines in config files act as spaces on the command line.

- config files can have lines starting with "#" to indicate that the
entire line is a comment

For string values that need spaces, the command-line quoting mechanism
of the shell must be used but does not need to be used in config files
(although it is allowed in config files).

The program has only one default value: a built-in default for the
"config" option that is set at compile time. On Unix-like systems, the
default config file is "/etc/simpleca.conf".

2.3 Notes on PKIX for SimpleCA users

This section explains a few PKIX terms as they are used in SimpleCA. It
is not a substitute for understanding the general concepts behind CAs
and how PKIX works. The book "Planning for PKI" by Russ Housley and Tim
Polk (ISBN 0471397024) gives much more detail in a very readable
fashion. Serious users might want to read the actual PKIX specifications
(although this is usually not necessary); see
<http://www.ietf.org/rfc/rfc3280.txt> for more information.

2.3.1 Enrollment

In the PKIX world, "enrollment" means "responding to a request for a
certificate". In SimpleCA, the request is always in the form of a file,
and the file has to be in PKCS 10 format. These files are sometimes
called "PKCS10 files", "certificate requests", and "certification
requests". There are a few online enrollment protocols for PKIX, but
they are not heavily used. Instead, most systems use PKCS10 files,
sometimes copied-and-pasted in web forms.

Basically, the end entity generates a certificate request file, gets it
to the SimpleCA system, the SimpleCA adminstrator generates a
certificate from it, and gets the certificate back to the user. Getting
the certificate request file into the SimpleCA system, and getting the
generated certificate back to the end entity, is done outside of
SimpleCA.

2.3.2 Names in certificates

Naming is by far one of the most difficult parts of the PKIX
specification. Different groups have interpreted the PKIX specifications
differently for how names should and should not be used. Basically, it's
a mess.

PKIX certificates have end entity names in four places: the issuer
field, the issuerAltName field, the subject field, and the
subjectAltName field. (The capitalization of these varies with their
use.) The issuer is the organization that creates the certificates. The
subject of a certificate is the entity that the certificate identifies.

Each field has one or more values. For example, a certificate might
have a subject field whose values say that "organization name is Example
Corportation, city is Anytown, country is US". Or it might have
a null subject name, but a subjectAltName field that says "email
address is [e-mail]".


3. General options

config=filename
Location of a config file to read. Can be used many times.

show-values
Shows the values for all options after processing all config files. This
does not stop processing of the rest of the commands; it just shows
the final value for all the values.

help, -help, --help, -?
Displays a list of all options, plus a bit of other explanatory text.
Causes all other options to be ignored. The value for this option (if
any is given) is ignored.

values
Displays all the values that can be used with options such as subj and
alt, even those defined in config file. Processes all options in order
to read all config files, but doesn't execute any commands. The value
for this option (if any is given) is ignored.

version
Shows the version of the program. Causes all other options to be
ignored.

view=filename
Shows the contents of a certificate, a certificate request, a key file,
or a certificate revocation list (CRL), in human-readable form. This
option cannot be given with options in the other sections.

cert-dup-dir=directoryname
Specifies a directory to write copies of all certificates and CRLs
that are created. If the directoryname is null, no writing is
done. This directory is useful because you need a copy of each
certificate that is to be included in a CRL.


4. Creating a CA

create-new-ca=filename
This creates a new self-signed CA certificate to the file named in the
option. It also creates a key file and an empty certificate revocation
list file, the names of which are prompted for. This option requires a
password that will be used for the new key file. If the password option
is not given, the password is prompted for; if the key-size option is
not given, it is assumed to be 1024 bits.

password=text
Specifies the password to be used for protecting the key file. This
option is also used in other commands to give the password for an
existing key file when needed.

key-size=number
Specifies the size of the key to be generated. If it is not given,
the default is 1024 bits.

crldp=string
The URL that is to go into the crlDistributionPoint field in the CA
certificate.


5. Issuing certificates

Note that some of these options involve strings that have punctuation
like semicolons, colons, and so on. If you are entering these options 
from the command line of an operating system that uses these 
punctuation marks as special, you will need to use command-line
quoting.

create-cert=filename
Creates a certificate at the given location. The priv-key
and request options must be set. If a file already exists at that
location, it is first backed-up with a time-stamped name.

priv-key=filename
Location of the CA's private key.

request=filename
Location of the PKCS10 certificate request used in the create-cert
option.

subj=string
Sets the subject field of the cert. The format is
"subj=[+]abbr:value;abbr:value...", where "abbr" is one of the
following:
   c
   cn
   l
   o
   ou
   sp
If the first character of the value is "+", the fields are added to
those already given in other options.

subj-alt=string
Sets the subjectAltName field of the cert. The format is
"subj-alt=[+]abbr:value;abbr:value...", where "abbr" is one of the
following:
   dns
   email
   ip
If the first character of the value is "+", the fields are added to
those already given in other options.

start-date=date
Date used for notBefore. This date must not be before the present
time.

end-date=date
Date used for notAfter.

key-usage=string
Turns on bits in the KeyUsage field. The format is
"key-usage=usagename;usagename...". The allowable usagenames are:
        digitalSignature
        nonRepudiation
        keyEncipherment
        dataEncipherment
        keyAgreement
        keyCertSign
        cRLSign
        encipherOnly
        decipherOnly
Capitalization is ignored in the usagenames. Not all of these can be
used in all certificates.

ext-key-usage=string
Turns on bits in the ExtKeyUsageSyntax field. The format is
"ext-key-usage=usagename;usagename...". The allowable usagenames are:
        codeSigning
        directoryService
        emailProtection
        ipsecEndSystem
        ipsecTunnel
        ipsecUser
        msCertTrustListSigning
        msTimestampSigning
        msEncryptedFilesystem
        msIndividualCodeSigning
        msCommercialCodeSigning
        msServerGatedCrypto
        nsServerGatedCrypto
        vsServerGatedCryptoCa
        serverAuth
        clientAuth
        timestamping
Capitalization is ignored in the usagenames. Not all of these can be
used in all certificates.


6. Updating a CRL

create-crl=filename
Creates a CRL file. The crl-contents and priv-key
options must be set. Th

crl-contents=filename
Location of a file that lists the certificates to be included in a CRL.
The format of the file is:
   cerificate-filename <tab> revocation date

crl-next-update=date
Date to be used for the nextUpdate value.


7. Utilities

create-keys=filename
Creates a file (in PKCS 15 format) that contains a public-private keypair.
This is useful for testing SimpleCA or other CA products. It is *not*
to be used for starting a CA. This option requires a password that will
be used for the new key file. If the password option is not given,
the password is prompted for; if the key-size option is not given, it
is assumed to be 1024 bits.

create-request=filename
Creates a certificate request in PKCS 10 format. This option requires
the name of the key file (in PKCS 15 format) that contains the public
key to be used in the certificate request. If the password option is not
given, the password is prompted for; if the key-size option is not
given, it is assumed to be 1024 bits.


8. Putting together certificates

After processing all the command line options and config files,
SimpleCA marshalls the items needed for a certificate. The following describes
decisions that it makes as it does this marshalling.

If the request option is given, the subject and all attributes are read
from the PKCS10 request. Later subj and alt options will overwrite the
values from the PKCS10 request.

If the start-date option is not set (even in the default config file),
the certificate is issued with notBefore set to the current time. If the
end-date option is not set (even in the default config file), the
certificate is issued with notAfter set to the current time plus five
years.


9. Default config file

key-usage=digitalSignature;dataEncipherment

start-date=0h
end-date=5y
crl-next-update=1d

10. Other notes

As one might imagine, the name "SimpleCA" has been used before for other
projects. For example, the Globus Project (the folks creating open
specifications for grid computing) have a front-end for OpenSSL called
"Simple CA"; see <http://www-fp.globus.org/security/simple-ca.html>.