# Server CA (make-ssl):

This directory contains a Makefile and an ssl.conf file to help you
manage a server CA, i.e. a CA to certify server keys. Although this is
supposed to complement make-ssl server package, with appropriate
configuration, it can be used independently.

## Philosophy
   
As in all other make-ssl packages, the basic idea is to manage the
affairs of a CA, mainly certifying/revoking a bunch of server in a
small to medium sized lab, through a set of Makefiles and ssl.conf
files. Usually in this setting the system administrator is herself the
CA and has access to the servers directly. These set of make files
automate the following work flow

(1) Set up a CA infrastructure on a independent machine. A small
    laptop servers this purpose well.

(2) Set up servers and generate SSL keys on these servers.
 
(3) Transfer the certificate requests from the server to the CA.

(4) Sign the certificate requests and transfer the certificates safely
    back to the server.

(5) Restart the server so that it starts using the new keys and
    certificates.


For better security, one would not want private keys to be transferred
at any point of time. Further for better security of the CA, we would
like to keep it offline, as much as possible.

Steps (3) and (4) can be over a public channel as long as an
eavesdropper cannot modified the sent request or grab the
certificate. This is because the data present in the request and
certificate are any way going to be public when the server starts
operational (they contain the public key and other public stuff).


Here is how one can automate these tasks using the MAKE-SSL/server-ca
package. The basic steps are as follows

1. Setup the CA infrastructure on a notebook by unpacking
   MAKE-SSL/server-ca package and configuring. This is a one time job.

2. Whenever a new SSL server is to be setup unpack and configure
   MAKE-SSL/server package in an appropriate directory on the server.

3. Make the CA aware of the new SSL server whose certificates will
   have to be managed.

4. Repeat step 3 and 4 for each of the servers that one wants to
   manage

5. Use <code>make update</code> and <code>make revoke</code> to update
   and revoke certificates.  For a help try <code>make help</code>.

These steps are explained in detail in the rest of the README

## Setting up the CA

1. Select a suitable machine for your CA. A small notebook will do.

2. Unpack the MAKE-SSL/server-ca.tar.gz into an appropriate location
   say CA_DIR.

3. Configure the CA key parameters by editing the file
   Makefile.configure and ssl.conf file. The main parameters to set
   are the variables PUBLIC_CRL_URL and PUBLIC_CERT_URL in
   Makefile.configure. The default setting for other parameters are
   just fine.

4. Type the command
    
         $ make ca

   This generates the necessary key, requests (if the CA is not a root
   CA) and certificates (if the CA is a root ca).

5. If your CA is not a root CA then you need to get your request
   signed by The appropriate CA and copy it to the location
   CA_DIR/.ca/certificate.pem.  Otherwise you are done.

This sets up the CA. This is a one time job.


## Setting up the server.

Let us say we want to setup a secure SMTP server. Let the name of the
server be smtp from now on.

1. Unpack the MAKE-SSL/server.tar.gz package into an appropriate
   location say SSL_DIR on the server.

2. Create a user, from now on called admin on the server. This user
   should have permissions to read and write from the directory
   SSL_DIR. One can avoid this by defining appropriate sudo commands
   but we will not describe that. The server end is now ready.

## Making the CA aware of our new server

That is easy. Boot up the CA and navigate into the directory
CA_DIR. Type the following command.

     $ make new server=smtp

This will create a directory for the server smtp under the directory
SERVER_DIR=${CADIR}/server/smtp and open the file
${SERVER_DIR}/Makefile.configure for configuring the details of the
server smtp. Details of what to configure is present in the
appropriate comments. The main variables of interest are the
following:

  * IS_SERVER_REMOTE: Most of the cases this will be yes. The only
    exception is if the CA can mount the SSL_DIR either via nfs (a
    dumb idea) or if the server is run on the CA machine itself (a
    extremely dumb idea).

  * SERVER_ADMIN and SERVER_HOSTNAME: If IS_SERVER_REMOTE is yes then
    the transmission of the request and response is done via scp. The
    variable SERVER_ADMIN is the appropriate user name (admin in our
    example) and the SERVER_HOSTNAME is the full host
    (smtp.example.com in our example) name by which the server can be
    accessed from the CA.

  * SERVER_SSL_PATH: The path of the SSL_DIR on the server relative to
    the home directory of admin@smtp.example.com. It is a better idea
    to set it as the absolute path on smtp.example.com.

That is all that you need provided admin@smtp.example.com has
appropriate read and write permissions in SERVER_SSL_PATH.  For more
complicated options read the CA_DIR/.skel/Makefile.configure (do not
modify this file).

At any point of time, if you want to reconfigure the server you can
type

     $ make configure server=smtp

## Updating the certificate of the server

You are now ready to update the certificates of the server smtp. Just
use the command

     $ make update server=smtp 

The server variable in this case can be set to a shell wildcard as
well. Thus the following command updates all servers.

     $ make update server='*' 

This is the command that you type for example when you do an yearly
update of certificates of all server that you have signed.


## Publishing Certificates and CRLs.

A CA is useless if its certificate is not available easily. Also,
unless CRLs are public and updated frequently, revocation of
certificates have no effect (what is the point in revoking without
informing). Hence it is better to maintain a homepage for the CA where
the certificate and CRL is published.

In the file Makefile.configure if the variables PUBLIC_CRL_URL and
PUBLIC_CERT_URL are set, then these certificates and CRLs can be
updated by a single command.

     $ make update-url


# On key compromise. 

  Take extreme care to make sure that all private keys are
secured. Any kind of compromise is a disaster. In case there is a
server compromise, revoke the keys as soon as possible.

      $ make revoke server=smtp  # revoke the servers certificate
      $ make crl                 # generate the new crl
      $ make update-url          # inform others of the revocation
                                 # see next section

  Now pray that all those who trust this CA update their crl reguarly,
a very unlikely proposition in a real network where people want 
"good enough" security and have "nothing to hide".

  A server compromise is probably one of the worst possible situation
you would be in.  But a CA compromise is even more problematic. So if
this happens contact all possible people using your CA and get then to
remove the CA certificate. Expire the keys and regenerate it. It is
better to start afresh.

      $ make revoke server='*'    # there is no point in this but still      
      $ make expire               # expire the CA keys and certificates
      $ make ca                   # regenerate the ca
      $ make crl		  # 
      $ make update-url


## Helps

For a brief but complete documentation try the following commands.

     $ make help target=TARGET # brief help on the target TARGET
     $ make help               # help on help


## Displaying CA information.

   To print the certificate, request, crl or the certificate
fingerprint of the CA use the command.

     $ make show info=[certificate|fingerprint|request|crl]
     
## Displaying server information.

   If the server variable is set in the above command the information
   of the server is shown instead.

     $ make show info=[certificate|fingerprint|request] server=WILDCARD

  As before shell wild cards can be used for server names for e.g.

     $ make show info=fingerprint server='*' 

  prints the fingerprints of certificates of all the server.

## Logs

   A log of the CA activities are maintained in CA.log. This can be
   checked.


## Cleaning up

     $ make obliterate # Wipes every thing clean (for testing only) 
     $ make expire     # expires the keys of the CA.
