If you want to use crtadm from the command line, either manually or using a script, there is a sub-package called cli that provide all services of the library.
The command line uses is provided through the '-jar' option of the JVM. For ewxample, the command below prints the built-in help. The pre-requisite for the JAR execution to work is the 'lib/' sub-directory containing the Bouncy-Castle crypto provider and the Jakarta Commons CLI library.
java -jar crtadmlib-1.0.jar --help
All command line snippets below, will not show the java/jar part, as shown above.
A root - sometime called CA (Certificate Authority) - certificate is need to sign other certs, such a server or client certificate. So before you begin, the first you will need to create is a root cert.
-root "CN=example.com,OU=root,O=Example,C=SE" -days 30 -out root.cert.xml
This will create a new root cert, valid for 100 days, and store both the cert and private key into the file 'root.cert.xml'. The argument to '-root' is the Distinguised Name and contains various fields separated by comma. The first is the Common Name and is generally used as the identification. For example, a browser prefer see the server name as the CN. For a full description of DN, you have too look elsewhere, for example here
-root <DN> [-days <num-days>] [-serial <serial-number>] [-out <cert-file>]
If you omit the output, it will print the XML to stdout. If you omit the serial number, it will use the full ISO8601 date-time (from year to milliseconds), where are digits are catenated, and form a BigInt serial number. This is indeed quite handy and is the recommended way, unless you want to keep track of cert sequence number. If you omit the number of days, it will generate a cerrt valid for 100 days.
A server cert can be used for HTTPS of a web server or TLS/SSL for a mail server. A client cert is intended to be used with HTTPS client cert authentication. You create both cert types in the same way, just a difference in the command.
-server <DN> -sign <root-cert> [-days <num-days>] [-serial <serial-number>] [-out <cert-file>] -client <DN> -sign <root-cert> [-days <num-days>] [-serial <serial-number>] [-out <cert-file>]
The signing cert is required and is the path to the root cert you created initially. All other options has the same meaning as for creating a root cert.
To use the generated certs in applications such as Apache, Postfix and Dovecot, you need to export the cert and private key parts into PEM format (some applications accept a catenated PEM file, but there is no benefit in doing this). To use a client cert in a browser for client cert authentication, you need to export the cert (including its root cert) into PKCS12 format.
You can export a cert into PEM, either in one go or separate.
-pem basename [-in <cert-file>] -pemcrt [<filename>] [-in <cert-file>] -pemkey [<filename>] [-in <cert-file>]
The first form generates both PEM files; one for the cert and one for the key. The basename is appended with '.crt.pem' and '.key.pem' respectively. If the input directive is omitted, it will read the cert file from stdin.
The two remaining forms, exports the cert and the key separetely. If the filename is omitted, it will print the PEM data to stdout. PEM data is just ASCII text and looks like this
-----BEGIN CERTIFICATE----- MIICyDCCAjGgAwIBAgIHR1bDhYA4AjANBgkqhkiG9w0BAQUFADBCMQswCQYDVQQG EwJTRTETMBEGA1UEChMKUmlib21hdGlvbjEPMA0GA1UECxMGdGVzdGVyMQ0wCwYD . . . LvEjb0YRz4icpFALiWjrfiz3NLriYXssSxrkeGTwZXZHAiua/1VdX39DPg0= -----END CERTIFICATE-----
To export a cert into the binary format PKCS12, you need to provide the target cert, its root cert and a password. The recognized file extension for PKCS12 files is '.p12', which means for example, that you can double-click on the file to import into a browser (MSIE).
-p12 [<filename>] -sign <root-cert> [-in <cert-file>] [-pwd <password>]
I the filename is omitted, it will print to stdout. PKCS12 is a binary format, which means it's advisable to either write to a file or redirect to a file. The root cert is required. If the input directive is omitted, it will read the cert from stdin. The password is normally required. However, if you omit the pwd directive, an empty password will be used. Keep that in mind when you import the p12 file into browser; when it prompts you for a password, just hit ENTER.
HTTPS with client cert authentication is great and has a higher level of security than password based authentication. However, there is one catch: I you need to withdraw a credential of a password based authentication, you just change the password or blocks the account. With client cert, there is no need to maintain an account (but nothing that prevents you from combining both schemes). That means, there must be a way to block access for a client cert, that is still valid.
The solution is called CRL (Certificate Revocation List) and requires two parts. The first is to create a CRL, which contains a list of the serial numbers of the blocked cert, all properly signed by the root cert. The second, is the central part: you must tell the authentication machinery about the CRL and keep it updated, when certs are withdrawn.
If you are using Apache, there is a special property to use, which refers to the CRL file. So when a cert needs to be withdrawn, the first step is to create a new CRL based on all previously withdrawn certs plus the new one. Then overwrite the previous CRL file, for Apache, and finally trigger Apache to re-read its configuration (Unix: kill -HUP pid . Debian/Ubuntu: sudo /etc/init.d/apache2 force-reload ).
A CRL has certain validity time, and must be specified. This is just loosly coupled to how frequently you withdraw certs. Be aware, that Apache might stop authenticate if the CRL has expired (has happened to me). It is probably a good idea to run a cron script that regenerates the CRL, so it never expires. The alternative is to set the number of days to a really high number. You can still re-create the CRL as many times you want, whenever a cert need to be withdrawn.
-crl [<cert-to-revoke>] -sign <root-cert> [-days <num-days>] [-serial <serial-number>] [-in [<crl-file>]] [-out <crl-file>]
The argument to 'crl' is the cert to revoke. If it is omitted, no new cert will be revoked. When you configure Apache, you typically will start with an empty CRL, so you can use a concrete filename in the httpd.conf. The signing root is required. If the input directive is omitted, no previous CRL will be considered, which is typically exactly what you want the first time you create a CRL. If you just specify '-in' without a crl file, it will read the CRL from stdin. If the output directive is omitted, it will write to stdout. The file format is PEM, which is plain ASCII.
The serial number is only needed, if you want to keep track of the sequence number. The default, when omitted, is to use the full ISO8601 data-time as the serial number. The default of the validity period is 100 days.