Cert Sorcerer Readme
--------------------

Cert Sorcerer (CS) is a tool for requesting certificates from the UK eScience CA
(although isn't endorsed or supported by them in any way). It was primarily
designed for users who want to request/renew host certificates and prefer a
console based workflow over a proprietary graphical application. CS is GPLv3
licensed, see COPYING for details.

** This tool is provided with no warranty what-so-ever, implied or otherwise. **


Installation
------------

The installation should be fairly straight forward, on RHEL you need the
following packages installed, they can all be found in the base repos.

- openssl
- python
- python-pycurl
- pyOpenSSL

It should then just be a case of copying CS.py somewhere, making it executable
and editing the header to set your site defaults. These should match the
parameters in your normal certificates, attempting to provide wrong values will
cause the CA to reject your request automatically.


Usage
-----

***** First you must customise CS.py for your site. *****

Edit CS.py to change the "Default Settings" section to match your parameters, if
you don't do this, your certificate requests will get rejected.

*********************************************************

All steps in a cert lifetime can be achieved just by calling CS.py with a CN.
User DNs contain a space, host DNs do not. If a single name is specified the
default domain name is automatically added.

For example to request a new hostcert just run this command and follow the
instructions:
CS.py myhost

If you're requesting a hostcert, you must have a valid user cert in ~/.globus/
to authenticate the request.

Once your cert has been approved by an RA and signed, running the same command
again will fetch the result into your (by default) ~/.cs directory.

Certs can be renewed by running the same command yet again.

You can optionally operate on the machine's primary hostcert by running:
 CS.py --sys
Internally this copies the hostcert into the CS store and then continues as if
you specified the full host name on the command line.

If you renew a hostcert containing an e-mail address, the renewed certificate
will not contain one. This is a feature, not a bug (DNs containing an e-mail
address are no-longer supported by most grid middleware).

Newly generated keys are automatically converted into PKCS#1 format when they
are created. This is to maintian compatibility with the majority of grid
middleware.


Bugs
----

There are certainly many bugs. Please send any bug reports to [email protected]
with a subject starting "CS Bug", remembering to include as much detail as
possible.


Internals
---------

The way this tool works is fairly straightforward. While it should clean-up
automatically after a crash, there may be a few instances where things are left
in an inconsistent state. If this happens to you, please report it as a bug. No
custom files are written by CS, so you should be able to recover from any state
by moving files around.

A hierarchy is created in the store directory (~/.cs) by default. For a hostcert
this looks like the following:

~/.cs/myhost.domain.name/key.pem - The key
~/.cs/myhost.domain.name/csr.pem - The CSR for the cert
~/.cs/myhost.domain.name/cert.pem - The cert
~/.cs/myhost.domain.name/key.pem.old - A copy of a pre-renewal key
~/.cs/myhost.domain.name/cert.pem.old - A copy of a pre-renewal cert

These files and directory should all be automatically created with permission
mode 0600 or 0700 for security. User certificates are the same, but any spaces
are replaced with underscores, i.e. ~/.cs/john_smith/cert.pem ...

If a cert.pem exists, then it is assumed a renewal should be done. If a csr.pem
exists (with no cert.pem) then CS will attempt to fetch a new certificate. If
neither of these exist then a new request is started from scratch.


The UK eScience CA seems to have its own web-service for requesting certificates.
This is predominately based around posting XML documents via HTTP. The required
subset of these requests can be seen/inferred from the CS_RemoteCA class.

The CA also seems to have its own authentication scheme called PPPK. This works
by adding a few challenge headers into the initial HTTP transaction, which will
then return HTTP 401. The client then calculates a response and re-sends the
request with a new response header (hopefully resulting in a HTTP 200). The core
for calculating the response is in the do_pppk function.