NAME

CSP - A wrapper around OpenSSL for maintaining multiple Certificate Authorities.

SYNOPSIS

  # csp help

DESCRIPTION

CSP is a perl module which uses openssl (openssl version 0.9.6 or later is required). Features include

o: CSP leaves subject naming policy to the user. No checks are made on the attribute names in the subject. This is good if you don't like being asked a lot of questions when issuing certificates.
o: Configuration is reduced to specification of extensions. This is simplified using a simple CPP/MPP-type macro interpreter in CSP.
o: CSP is designed to easily handle multiple distinct Certificate Authorities. Hence the name which stands for Certificate Service Provider.
o: CSP can be used to produce a web site (certificate repository, CRLs etc etc) without the need for cgi-scripts.
o: CSP tries to be as PKIX-compliant as OpenSSL allows.

CSP IN PRACTICE

The typical application for CSP is a small CA (which may or may not be part of a larger pki) issuing mainly server and object signing certificates and only few if any user certificates. The distinction between user and other certificates may seem arbitrary but experience shows that managing a large set of user certificates typically requires a more sofisticated system for managing and tracking requests.

When setting up CSP for production use the author strongly recommends using a non network connected host for the CA operations. This computer will not use much CPU or disk resources and any old PC with Linux or *BSD should work admirably. An old laptop might be a very good choice since it can be locked away when not in use. It might be a good idea to equip the computer with a cd writer or some other means for making backups of the certificate directory. Day to day operations include the following tasks.

1.: Issuing certificates based on pkcs10 or out-of-band (non pkcs10) requests.
2.: Backing up the csp main directory (see below) to read-only medium.
3.: Producing the public web site and exporting it (typically using floppy or zip-drive) to your web server.

CONFIGURATION

First set the environment variable OPENSSL to contain the absolute path of your OpenSSL binary. This is a requirement for everything that follows. Next create a directory where you will keep your CAs. This can be any directory anywhere in your file system owned by anyone. A sample directory "ca" in the distribution is included as a reference. A good way to get started is to copy this directory somewhere. Set $CSPHOME to point to this directory. The layout of this directory is as follows:

 .
 |-- csp                  Certificate Authorities directory
 `-- etc                        
     |-- aliases.txt          Alternative names for DN attributes
     |-- extensions.conf      Default certificate extensions file
     |-- crl_extensions.conf  Default crl extensions
     |-- oids.conf            Extra OIDs (eg attribute types).
     |-- public_html          Default web site template files
     `-- types.txt            List of certificate types to support

Most of these files are defaults that are copied to each new CA when created. This means that if you need defaults used by all CAs you create you must make those edits first of all.

The oids.conf and aliases.txt should be edited to include support for any extra attribute types your CA systems must support. The format of these files should be obvious. The oids.conf includes support for the DC attribute.

Next edit extensions.conf. This file is a default file which is copied to each new CA. Before you create your first CA edit this file to reflect extensions and defaults for all CAs created in this directory. The format of this file is explained in the EXTENSIONS section. Also edit the crl_extensions.conf to include support for any crl extensions you might need. Remember that after you create a CA you must edit the local copy of these files to reflect the requirements of that particular CA.

Finally edit the files in public_html. The structure of this directory is explained in more detail in the section WEBSITE below.

You are now ready to create your first CA. If this is a self-signed CA creation is done in two steps: First create the directories and copy the configuration files. The first argument "PCA" is a name of the CA in our example. Creation of the CA "PCA" is done using the command "csp create".

 [leifj@njal CSP]$ ./csp PCA create

Next initialize "PCA". The last argument is the distinguished name of the CA. CSP does not impose any limit on names which means that you can get away with any DN as long as your oids.conf and aliases.txt include aliases and oids for the attribute types.

 [leifj@njal CSP]$ ./csp PCA init --keysize=2048 \
                   --days=2190 'CN=CA,dc=example,dc=com'
 [CSP][PCA     ] Generating CA key
 [CSP][PCA     ] Private key password: <...>
 [CSP][PCA     ] Re-enter Private key password: <...>
 [CSP][PCA     ] Successfully created CA PCA

List the contents of this certificate provider:

 [leifj@njal CSP]$ ./csp --list
 PCA

Use openssl to dump the contents of the CA certificate:

 [leifj@njal CSP]$ csp PCA dump

 ... stuff deleted ...

Now issue a new server certificate signed by PCA:

 [leifj@njal CSP]$ ./csp PCA issue \
                     --keysize=1024 \
                     --noconfirm \
                     'CN=www.example.com,dc=example,dc=com'
 [CSP][PCA     ] Generating new key
 [CSP][PCA     ] Private key password: <...>
 [CSP][PCA     ] Re-enter Private key password: <...>
 [CSP][PCA     ] Create certificate request for CN=CA,dc=su,dc=se
 [CSP][PCA     ] Signing request

Check the contents of PCA database (the --xinfo arg gives you the sha1 and md5 fingerprints)

 [leifj@njal CSP]$ ./csp PCA list --xinfo
 Serial  : 01
 Status  : Valid
 Subject : CN=www.example.com,dc=example,dc=com
 Expires : Wed Oct 10 10:28:32 2001
 SHA1    : A3:53:D7:DF:AE:A2:44:0A:0F:B8:29:31:E7:96:16:62:1F:52:DF:62
 MD5     : 04:2A:3A:1B:BB:B9:1E:08:4D:C3:14:CE:71:72:CC:86

Finally generate the public web site

 [leifj@njal CSP]$ mkdir /tmp/export
 [leifj@njal CSP]$ ./csp PCA genpublic --export=/tmp/export

Now move /tmp/export to a removable medium and transport it to your web server.

EXTENSIONS

Configuration of extensions is done in the etc/<ca name>extensions.conf. The format of this file is equivalent to the openssl extensions format. Read more about this in the openssl documentation. This file also supports a simple macro format similar to transarc mpp which in turn is essentially CPP with '%' as the magic character. The following macros are supported:

 %ifdef/%endif
 %if/%endif
 %include

The predicate in the %if macro can be almost any perl expression where macro %-expansion replaces perl variable expansion.

WEB SITE

The directory public_html in each CA directory contains template files (MPP macro expansion is applied to these files) for a public web site. The included example has the following organization

  public_html
  |-- certs
  |   |-- cert.html.mpp
  |   |-- expired.html.mpp
  |   |-- index.html.mpp
  |   |-- revoked.html.mpp
  |   |-- valid.html.mpp
  `-- index.html.mpp

The csp command "csp genpublic" will produce a directory in the export directory (specified by --export) which looks like this:

  <export>
  |-- ca.crt
  |-- certs
  |   |-- 01.crt
  |   |-- 01.html
  |   |-- 01.pem
  |   |-- expired.html
  |   |-- index.html
  |   |-- revoked.html
  |   `-- valid.html
  |-- crl-v1.crl
  |-- crl-v2.crl
  `-- index.html

The ca.crt, crl-v1.crl and crl-v2.crl are copies of the corresponding files from the master repository. Each certificate in the repository is stored in <export>/certs as DER, PEM and as an HTML page derived from public_html/certs/cert.html.mpp by macro expansion. All other pages are simply produced by macro expansion of the corresponding .mpp-files and apart from certs/cert.html.mpp none of these files need exist or have the names they have in the example above.

When performing macro expansion on public_html/certs/cert.html.mpp the following variables are available:

  DATE              The date (using localtime(time)) of 
                    the export operation.
  SUBJECT_SERIAL    The serial number of the certificate.
  SUBJECT_DN        The distinguished name (DN) of the 
                    certificate.
  ISSUER_DN         The distinguished name (DN) of the 
                    CA certificate.
  SUBJECT_SHA1      The SHA1-fingerprint of the 
                    certificate.
  SUBJECT_MD5       The MD5-fingerprint of the 
                    certificate.
  SUBJECT_NOTBEFORE The date when this certificate 
                    becomes valid.
  SUBJECT_NOTAFTER  The date when this certificate 
                    expires.

When all other files in the directories (public_html and public_html/certs) are run through the macro preprocessor to produce HTML files the following variables are available:

  DATE               The date (using localtime(time)) of 
                     the export operation.
  VALID              An HTML table of valid certificates.
  VALID_COUNT        The number of valid certificates.
  REVOKED            An HTML table of revoked certificates.
  REVOKED_COUNT      The number of revoked certificates.
  EXPIRED            An HTML table of expired certificates.
  EXPIRED_COUNT      The number of expired certificates.
  SUBJECT_SERIAL     The serial number of the CA certificate.
  SUBJECT_NOTAFTER   The date when the CA certificate 
                     expires.
  SUBJECT_NOTBEFORE  The date when the CA certificate 
                     became valid.
  SUBJECT_DN         The distinguished name (DN) of the 
                     CA certificate.
  SUBJECT_MD5        The MD5-fingerprint of the CA 
                     certificate.
  SUBJECT_SHA1       The SHA1-fingerprint of the CA 
                     certificate.

AUTHOR

Leif Johansson <leifj@it.su.se> Stockholm University

ACKNOWLEDGEMENTS

The web site generation was inspired by work by Heinar Hillbom <Einar.Hillbom@umdac.umu.se> UMDAC, Umeå Universitet

POD ERRORS

Hey! The above document had some coding errors, which are explained below:

Around line 1800:: Non-ASCII character seen before =encoding in 'Umeå'. Assuming CP1252