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 sf105@ic.ac.uk 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.