micro-ca is a trivial-to-use shell script for managing a local Certificate Authority (CA). It was designed to create certificates for a small, private group of users, such as an openvpn-based private network or an infinoted (gobby) server with a limited group of users.
micro-ca uses the openssl req and openssl x509 commands to create keys, requests, and certificates. It does not use any external openssl config (e.g. the default /etc/ssl/openssl.cnf). It creates an almost-empty openssl.cnf file in the micro-ca directory to overcome what I consider to be a bug in the openssl req -x509 command when creating the self-signed root CA certificate (it requires a distinguished_name value, even when the subject is specified on the command line and the distinguished_name from the config file is not used).
To use micro-ca, create an empty directory with appropriate permissions (suggested 0700 or 0750). This directory must always be the current directory when running micro-ca. Edit micro-ca.cnf in this directory as described under Configuration below, or run
$ micro-ca init
and answer a few simple questions to create the config file for you. Entering an empty response to any prompt will abort without creating the config file.
When you are satisfied with the config file, run
$ micro-ca root
to create the root CA certificate. Then, for each user certificate run
$ micro-ca newuser «username» «email»
to initialize the user's certificate directory and create the initial certificate.
When the root CA certificate is nearing expiration, run
$ micro-ca root
again to update it. Nothing will be done if the certificate is not within the configured number of days of expiration, unless you use the --force option as well:
$ micro-ca --force root
will create a new certificate even if the current one is not expiring soon.
To update a user certificate, run
$ micro-ca user «username»
which also will only update the certificate if it is nearing expiration. The --force option can be used as with the root CA certificate. In neither case will --force overwrite an existing certificate, which has the creation date as YYYYMMDD as part of the filename. If you really wish to, rename or remove the current certificate before updating.
The newuser and user commands are distinct for two reasons: the newuser command needs an additional email argument, and it makes it harder to accidentally create a new user with the wrong name by mistyping the user name while attempting to update an existing user.
Distribution of and security for the certificates and their associated private keys are not managed by micro-ca (except that openssl creates the key file with permissions 0600). Common sense dictates that you only use micro-ca on a machine whose security matches or exceeds the security needs of your root CA certificate. Also, be sure to set the permissions on the micro-ca directory appropriately.
By default, micro-ca uses the -nodes option to openssl when creating keys to avoid requiring a password to use the root CA and user certificates. A future version of micro-ca will allow overriding this in the config file.
The configuration file is named micro-ca.cnf and must be in the current directory when micro-ca is run (typically a subdirectory of the CA admin's home directory). In addition to micro-ca.cnf, this directory will contain the files serial and openssl.cnf, and the directories ca and users. The ca directory will contain the root CA certificates and keys. A subdirectory of users will be created for each user to contain that user's certificates and keys.
The config file is sourced by the micro-ca script, so be careful what you put in it; it should only contain comments and variable assignments.
The following variables must be defined in micro-ca.cnf for proper operation of micro-ca:
CA_CN: The Common Name for the root CA certificate subject. CA_EMAIL: The email address for contacting the CA admin. CA_O: The Organization for the certificate subject. This will be used for both the root CA certificate and the user certificates. CA_DAYS: The lifetime in days of the root CA certificate. For practical reasons, this should be at least twice the lifetime of the user certificates, plus a margin. For a use case where the risk of being compromised is low, ten years (3700 days) might be a good choice. CA_RENEW: The number of days prior to expiration to allow renewal of the root CA certificate (without the --force option). This should be longer than the lifetime of a user certificate plus a margin. 1200 days would be a reasonable choice with the example values given for CA_DAYS and USER_DAYS. USER_DAYS: The lifetime in days of a user certificate. Three years (1100 days) could be a reasonable value for our hypothetical low-risk scenario. USER_RENEW: The number of days prior to expiration to allow renewal of a user certificate (without the --force option). I might use 100 days with the above example values for CA_DAYS and USER_DAYS.
The following variables will be used if they are defined, but are not required:
CA_OU: The Organizational Unit for the root CA certificate subject. CA_C: The Country for the root CA certificate subject. CA_ST: The State or Province for the root CA certificate subject. CA_L: The Locality (city) for the root CA certificate subject.
I will likely add similar variables for USER soon.
The following variables control aspects of micro-ca that are not normally changed by the CA admin. They are defined in the micro-ca script itself before the config file is sourced. If you wish to use non-standard values for any of these, define them in the config file, rather than changing micro-ca.
CA_DIR: The name of the directory containing the CA keys and certificates. (default: "./ca") USER_DIR: The name of the directory containing the user directories for their keys and certificates. (default: "./users") SSL_CNF: The name of the "dummy" openssl config file. (default: "./openssl.cnf") SERIAL_FILE: The name of the file containing the next serial number to use for user certificates. (default: "./serial") SERIAL_INIT: The initial value to place in the serial number file. This variable is only used if the serial number file doesn't exist when a command other than init is used. (default: 1001)
It is generally considered bad practice to issue two certificates with the same serial number, so if the serial file is deleted accidentally (or otherwise!), you should manually create it with a value that is larger than any serial number already used.