Less Awful SSL
Working with Java's crypto libraries requires deep knowledge of a complex API, language-specific key+certificate storage, and knowing how to avoid long-standing bugs in the Java trust algorithms. This library tries to make it less complicated to build simple SSL-enabled applications: given a CA certificate and a signed key and cert, it can give you an SSLContext suitable for creating TCPSockets directly, or handing off to Netty.
Installation
https://clojars.org/less-awful-ssl
Example
In this example we'll be using OpenSSL's stock CA configuration and the OpenSSL perl script to create a CA's directory structure. I'm assuming you want your CA signing key encrypted, but the client and server keys unencrypted (since they'll be deployed to processes which run without human interaction).
# Create the CA directory hierarchy and keypair
# http://kremvax.net/howto/ssl-openssl-ca.html
cp /usr/lib/ssl/misc/CA.pl ca
./ca -newca
# Generate a server key
openssl genrsa -out server.key 4096
# Convert key to pcks8 because Java can't read OpenSSL's format
openssl pkcs8 -topk8 -nocrypt -in server.key -out server.pkcs8
# Generate a cert request
openssl req -new -key server.key -out newreq.pem
# Sign request with CA
./ca -sign
# Rename signed cert and clean up unused files
mv newcert.pem server.crt
rm newreq.pem server.key
# And generate a client key+cert as well
openssl genrsa -out client.key 4096
openssl pkcs8 -topk8 -nocrypt -in client.key -out client.pkcs8
openssl req -new -key client.key -out newreq.pem
./ca -sign
mv newcert.pem client.crt
rm newreq.pem client.key
Now fire up a repl and test that your client and server keys can work together.
(test-ssl)
takes a client key and cert, a server key and cert, and a trusted
CA certificate, and verifies that a client can talk to the server over a TLS
socket:
(use 'less.awful.ssl)
(def d (partial str "/path/to/keys/"))
(apply test-ssl (map d ["client.pkcs8" "client.crt" "server.pkcs8" "server.crt" "demoCA/cacert.pem"]))
:accepting
:connecting
:accepted
:connected
:client-sent
:server-got "hi"
:server-sent "hi"
:client-got "hi"
:client-done
:waiting-for-server
:server-done
Note that this doesn't work if you substitute some other certificate for the trust chain, rather than the CA's:
(apply test-ssl (map d ["client.pkcs8" "client.crt" "server.pkcs8" "server.crt" "server.crt"]))
:accepting
:connecting
:connected:accepted
javax.net.ssl.SSLHandshakeException: null cert chain
...
SSLHandshakeException Received fatal alert: bad_certificate
sun.security.ssl.Alerts.getSSLException (Alerts.java:192)
In your app, you'll want to distribute a particular PKCS secret key, the corresponding signed certificate, and the CA certificate (to verify the peer's identity). Then you can build an SSLContext:
(ssl-context "client.pkcs8" "client.crt" "ca.crt")
And given an SSL context, you can use it to construct a server or a client TCP
socket. See core.clj/test-ssl
for an example:
(with-open [listener (-> (ssl-context "server.pkcs8" "server.crt" "ca.crt")
(server-socket "localhost" 1234))
conn (.accept sock)]
...)
(with-open [sock (-> (ssl-context "client.pkcs8" "server.crt" "ca.crt")
(socket "localhost" 1234)]
...)
Example with a PKCS12 client certificate and org.httpkit
Assume you've got a client key/certificate pair for example.com
as a PKCS12 file client.p12
,
secured with password. Also, you've got the Certificate Autority that was used to
sign the client certificate as ca-cert.crt
.
Then you could do (your project needs http-kit, of course):
(use 'less.awful.ssl)
(require '[org.httpkit.client :as http])
(def password (char-array "secret"))
(def req (http/request {:sslengine (ssl-context->engine (ssl-p12-context "client.p12" password "ca-cert.crt"))
:url "https://example.com/needs-client-cert" :as :stream}))
Thanks
I am indebted to Ben Linsay and Palomino Labs (http://blog.palominolabs.com/2011/10/18/java-2-way-tlsssl-client-certificates-and-pkcs12-vs-jks-keystores/) for their help in getting this all put together.
License
Copyright © 2013 Kyle Kingsbury ([email protected])
Distributed under the Eclipse Public License, the same as Clojure.