diff --git a/README.md b/README.md new file mode 100644 index 0000000..94915ea --- /dev/null +++ b/README.md @@ -0,0 +1,128 @@ +ca-scripts +========== + +A set of `bash(1)` scripts for working with SSL Certificate Authorities. + +These scripts are designed to provide a configurable wrapping layer around +[openssl](http://www.openssl.org/), similar to CA.pl. They're potentially a +little heavyweight if you just need a single self-signed certificate to secure +an HTTPs webserver, but they may come in handy if you want to: + + * Generate multiple service certificates signed by a single authority + * Provide signed client certificates to end users for authentication purposes + * Provide client certificates for S/MIME encrypted e-mail or code signing + * Easily set extensions such as x509v3 subjectAltName in your certificates + +Installation +------------ + +There aren't any tarballs as yet. Nor will the `make` command below work until +I've written a Makefile. It's coming, sometime. Sorry ;-) + + $ git clone git://github.com/fluffle/ca-scripts + $ cd ca-scripts + $ make; sudo make install + +This will by default install to `/usr/local`, either `export PREFIX=/path` or +`make PREFIX=/path; sudo make PREFIX=/path install` to change this to an +alternative location. + +Creating a Certificate Authority +-------------------------------- + + Before running `ca-init(1)`, a configuration file for the CA scripts must be +created. This configuration file sets up some templating variables that will +be present in certificates created for this CA, such as the domain, CA name, +and the root directory which will be populated with the generated certificates. +An example configuration file is provided with the scripts, and the comments +should be self-explanatory. + + By default the CA scripts will read `/etc/ca-scripts.conf`. This is fine for +creating a single CA serving a single domain with no intermediary certificates, +but for a more complex setup a directory of configuration files will probably +be needed. Some settings are required, namely the `CA_HOME`, `CA_DOMAIN`, and +`CA_DN_*` variables, while others can be inferred from these or have sensible +defaults set. See `ca-scripts.conf(5)` for more detail on these. + + Once the configuration has been created the initial CA setup can be performed +with `ca-init(1)`, but please note that the path set in `CA_HOME` must exist and +be writeable before it will run correctly. It is recommended (but not in any way +required) to create an unprivileged "`ssl`" user to run all the scripts as, so +the permissions are correctly set. A number of subdirectories will be set +up underneath this root, and an openssl configuration file, certificate and +private key will be generated. This key can be 3DES encrypted for security. + + Optionally, it is possible to split the initial setup process so that the +directory structure and openssl configuration generation can be done in a +seperate step to the generation of the CA certificates, so that the config can +be manually edited. To fully understand it's contents you're unfortunately +going to need to read `ca(1ssl)`, `req(1ssl)`, `x509(1ssl)`, `config(5ssl)`, +and `x509v3_config(5ssl)`. Particularly important are the x509v3 extensions +present in the certificate, which are defined in the "ca\_x509\_extensions" +section of the config file. + +Creating a certificate +---------------------- + + The `ca-create-cert(1)` script can generate three "types" of certificate: +server certificates for securing a service with SSL/TLS; client certificates +for authenticating a client to these services; and user certificates for +authentication, S/MIME e-mail signing or encryption, and code signing. There +are minor but important differences in the key usage extensions present in +these different certificate types, details can be found in the extension +templates provided with the scripts. + + `ca-create-cert(1)` takes a number of options to customise the generated +certificate. The `--type` option is mandatory, and for server certs it is very +likely that the `--alt-name` option will be useful to set x509v3 subjectAltName +DNS records for other hostnames for the server. Both the server hostname and +any alternative names will be fully-qualified to `CA_DOMAIN` if they do not +contain any dots, but if unqualified names are passed in they are also +preserved as alternative DNS names in the certificate. The private key may be +encrypted with 3DES, and optionally the certificate, key, and CA certificate +can be bundled together into a PKCS#12 format certificate archive. By default +certificates are valid for 365 days from signing, but this may be changed with +the `--days` option. + + The certificate's DN can be completely changed from the defaults provided by +`ca-scripts.conf(5)`, but be wary as by default the generated openssl config +file requires that the country (C) and organisation (O) fields match those of +the CA certificate. A comment may also be set that will show up in user browsers +when they click on their padlock icons to examine the certificate's properties. +As with the CA setup, the steps to generate the certificate can be split up so +that configurations that are created from templates can be edited beforehand. + +Renewing a certificate +---------------------- + + Certificates are renewed using `ca-renew-cert(1)`. This script currently does +some painful certificate manipulation that is not strictly necessary in most +cases, and may in fact decrease SSL security slightly. This is done because +the normal renewal process re-generates the certificate signing request and +thus creates a new public/private keypair. If the certificates are used for +S/MIME encryption or code signing, this renders all the encrypted e-mail +unreadable and requires you to re-sign the code with your new private key. + + To avoid this, `ca-renew-cert(1)` re-signs the old certificate request with a +a new expiry date using the extensions generated when the old certificate was +signed. In the future it is possible (even likely) that this renewal method +will only be used on "user" type certificates, and the "server" and "client" +types will be renewed normally. If the current renewal method doesn't provide +sufficient security, the current certificate should be revoked and a new one +generated that is valid for the correct period of time using the `--days` option +to `ca-create-cert(1)`. + + As with the certificate creation script the `--type` option is mandatory for +`ca-renew-cert(1)`, but the argument may be either a hostname, a username or a +path to a certificate. Internally this will be resolved to the correct +information required for certificate renewal. + +Revoking a certificate +---------------------- + + To revoke a certificate and re-generate the CA certficate revocation list in +both PEM and DER encodings, invoke `ca-revoke-cert(1)`, again providing the +`--type` option and either the hostname, username or the path to the certificate +to be revoked. Along with `ca_init(1)` this script can optionally generate a +basic HTML template to serve the CA certificate and CRL with verifiable MD5 and +SHA1 checksums. diff --git a/doc/README b/doc/README deleted file mode 100644 index 2fd750b..0000000 --- a/doc/README +++ /dev/null @@ -1,95 +0,0 @@ -1. Creating a Certificate Authority. - - Before running ca-init(1), a configuration file for the CA scripts must be -created. This configuration file sets up some templating variables that will -be present in certificates created for this CA, such as the domain, CA name, -and the root directory which will be populated with the generated certificates. -An example configuration file is provided with the scripts, and the comments -should be self-explanatory. - - By default the CA scripts will read /etc/ca-scripts.conf. This is fine for -creating a single CA serving a single domain with no intermediary certificates, -but for a more complex setup a directory of configuration files will probably -be needed. Some settings are required, namely the CA_HOME, CA_DOMAIN, and -CA_DN_* variables, while others can be inferred from these or have sensible -defaults set. See ca-scripts.conf(5) for more detail on these. - - Once the configuration has been created the initial CA setup can be performed -with ca-init(1), but please note that the path set in CA_HOME must exist and be -writeable before it will run correctly. It is recommended (but not in any way -required) to create an unprivileged "ssl" user to run all the scripts as, so -the permissions are correctly set. A number of subdirectories will be set -up underneath this root, and an openssl configuration file, certificate and -private key will be generated. This key can be 3DES encrypted for security. - - Optionally, it is possible to split the initial setup process so that the -directory structure and openssl configuration generation can be done in a -seperate step to the generation of the CA certificates, so that the config can -be manually edited. To fully understand it's contents you're unfortunately -going to need to read ca(1ssl), req(1ssl), x509(1ssl), config(5ssl), and -x509v3_config(5ssl). Particularly important are the x509v3 extensions present -in the certificate, which are defined in the "ca_x509_extensions" section of -the config file. - -2. Creating a certificate. - - The ca-create-cert(1) script can generate three "types" of certificate: -server certificates for securing a service with SSL/TLS; client certificates -for authenticating a client to these services; and user certificates for -authentication, S/MIME e-mail signing or encryption, and code signing. There -are minor but important differences in the key usage extensions present in -these different certificate types, details can be found in the extension -templates provided with the scripts. - - ca-create-cert(1) takes a number of options to customise the generated -certificate. The --type option is mandatory, and for server certs it is very -likely that the --alt-name option will be useful to set x509v3 subjectAltName -DNS records for other hostnames for the server. Both the server hostname and -any alternative names will be fully-qualified to CA_DOMAIN if they do not -contain any dots, but if unqualified names are passed in they are also -preserved as alternative DNS names in the certificate. The private key may be -encrypted with 3DES, and optionally the certificate, key, and CA certificate -can be bundled together into a PKCS#12 format certificate archive. By default -certificates are valid for 365 days from signing, but this may be changed with -the --days option. - - The certificate's DN can be completely changed from the defaults provided by -ca-scripts.conf(5), but be wary as by default the generated openssl config file -requires that the country (C) and organisation (O) fields match those of the CA -certificate. A comment may also be set that will show up in user browsers when -they click on their padlock icons to examine the certificate's properties. As -with the CA setup, the steps to generate the certificate can be split up so -that configurations that are created from templates can be edited beforehand. - -3. Renewing a certificate. - - Certificates are renewed using ca-renew-cert(1). This script currently does -some painful certificate manipulation that is not strictly necessary in most -cases, and may in fact decrease SSL security slightly. This is done because -the normal renewal process re-generates the certificate signing request and -thus creates a new public/private keypair. If the certificates are used for -S/MIME encryption or code signing, this renders all the encrypted e-mail -unreadable and requires you to re-sign the code with your new private key. - - To avoid this, ca-renew-cert(1) re-signs the old certificate request with a -a new expiry date using the extensions generated when the old certificate was -signed. In the future it is possible (even likely) that this renewal method -will only be used on "user" type certificates, and the "server" and "client" -types will be renewed normally. If the current renewal method doesn't provide -sufficient security, the current certificate should be revoked and a new one -generated that is valid for the correct period of time using the --days option -to ca-create-cert(1). - - As with the certificate creation script the --type option is mandatory for -ca-renew-cert(1), but the argument may be either a hostname, a username or a -path to a certificate. Internally this will be resolved to the correct -information required for certificate renewal. - -4. Revoking a certificate. - - To revoke a certificate and re-generate the CA certficate revocation list in -both PEM and DER encodings, invoke ca-revoke-cert(1), again providing the ---type option and either the hostname, username or the path to the certificate -to be revoked. Along with ca_init(1) this script can optionally generate a -basic HTML template to serve the CA certificate and CRL with verifiable MD5 and -SHA1 checksums.