There is a patently easy way to convert JKS keystores to PKCS12 certificate bundles (and vice versa). It’s a (poorly documented) keytool command that was introduced with JDK 6:
Convert JKS to P12
keytool -importkeystore -srckeystore keystore.jks -srcstoretype JKS -deststoretype PKCS12 -destkeystore keystore.p12
Convert P12 to JKS
keytool -importkeystore -srckeystore keystore.p12 -srcstoretype PKCS12 -deststoretype JKS -destkeystore keystore.jks
There are two ways to set up client authentication – the “correct” way (where you have all of your secured content in its own virtual host) and the “useful” way (where you want to have your secured content in a directory rather than the entire site).
The “useful” way involves renegotiating the SSL connection when accessing the secured content (i.e., the connection is negotiated once when you request https://www.example.com/ and then renegotiated when you request https://www.example.com/client-auth-required/). This was all fine and well, but an OpenSSL vulnerability was discovered where renegotiation handshakes were not properly associated with the existing connection – thus potentially allowing for a Man-in-the-Middle attack.
OpenSSL 0.9.8m was released to fix the bug – the fix was to switch to a newer and more poorly supported method of allowing renegotiations. Practical outcome: client authentication in many web apps using Apache and mod_ssl simply stopped working.
Sometimes you need client authentication at a directory level, and chances are you want to make it work with commonly used web browsers (i.e., Internet Explorer). Here’s how you do it:
The method of configuring client authentication as described below intentionally turns back on a known security vulnerability in Apache. For obvious reasons, this isn’t recommended. If you can, set up your secured content in its own virtual host (the “correct” way).
This recipe makes use of the following ingredients:
If you haven’t got the above two items, you need to fix that first.
Assumption: you’ve already got SSL set up and working – there are at least 9000 howto’s on the Internets, so little point in covering that here.
Once you have SSL working without error, you’ll need to add this to your VirtualHost configuration:
SSLVerifyClient require
SSLVerifyDepth x
SSLCACertificateFile /path/to/client-cert-issuing-chain.crt
SSLCADNRequestFile /path/to/client-cert-issuing-ca.crt
SSLInsecureRenegotiation on
The first line requires a certificate from the client.
The second line tells the server how far down it can traverse a chain to verify a certificate before giving up – 1 if the certificate is directly signed by a Root CA, 2 if there’s one Intermediate CA and so on.
The third line tells the server what CAs to trust for client authentication; if you have a chained hierarchy for issuing client certificates, this file should contain all of the Intermediate CAs up to and including the Root CA (concatenated together in PEM format). Not sure what version of Apache started requiring the full chain, but you’ll get non-obvious errors in your log files if you don’t have all of the CAs required here.
The fourth line tells the client what CAs the server will accept a certificate for, and should point to a file containing the Issuing CA (in PEM format) for your client certificates. This command is particularly important if you use an Intermediate CA to issue client certificates. It’s optional – and doesn’t get used to actually validate client certificates – but Internet Explorer pays attention to this statement when working out a list of acceptable client certificates for the user to pick from, so it’s not such a bad idea to include it.
The fifth line does exactly what it says; it’s what actually makes client authentication work at a directory level. Do note that the fifth line is only valid within a Server or Virtual Host context; you can’t use it in a Directory or Location section.
You will then need the following at the Directory level:
SSLRequireSSL
<FilesMatch “.(cgi|pl)$”>
SSLOptions +StdEnvVars
</FilesMatch>
Obviously this is in addition to whatever else you have configured for the Directory section.
The first line requires a SSL’ed connection.
The FilesMatch section and SSLOptions statement aren’t absolutely required, but if you want to log any of the information from the client certificate the user is presenting, or make said information available in the environment variables – you’ll need it. Grabbing all this information comes at a performance penalty, so it makes good sense to restrict what types of files the server extracts it for.
Another item worth researching and including in your config is the SSLRequire directive – it’s reasonably complicated, but allows you to control what client certificates are allowed based on things like Subject DN and Issuer DN.
One last thing: make a point of reading the mod_ssl documentation. You’ll be glad you did!