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 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 chris@example.com". 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 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 .