Trust the Client's Root CA

Currently, we're telling RabbitMQ to look at the testca/cacert.pem file. This contains just the public certificate of our test Certificate Authority. We may have certificates being presented by clients which have been signed by several different Certificate Authorities, and we wish RabbitMQ to trust all of them. Therefore, we can simply append these certificates to one another and provide the path to this new file as the cacerts argument to RabbitMQ:

# cat testca/cacert.pem >> all_cacerts.pem
# cat otherca/cacert.pem >> all_cacerts.pem

and so forth.

Bugs in new_ssl

In Erlang before release R13B02, the new_ssl application has a bug in which, if it asks the peer for a certificate, and the peer totally fails to respond to this request rather than rejecting the connection, the new_ssl application permits the connection to be established. Note that this requires the client to break the SSL specifications itself: the specifications require that if the client has no certificate to send and a certificate has been requested by the server, the client must send back a null certificate. If this happens, then the new_ssl application behaves correctly, and acts on the presence of the null certificate.

If the client fails to send any certificate at all, the new_ssl application silently ignores this failure and allows the connection to be established (i.e. it doesn't enforce that if it demands a certificate, a certificate really is sent back by the client).

In Erlang release R13B02, the above behaviour has been fixed: if the client is asked to present a certificate, then it must do so. However, other bugs have been introduced: in particular, the fail_if_no_peer_cert is not honoured any more, meaning that if you set {verify, verify_peer}, then clients must present a certificate. I.e. it is not possible to now permit the case where either a client presents no certificate, or it presents a certificate for which we can verify a chain of trust.

See also the bugs in Mono.

Key Managers, Trust Managers and Stores

There are three components to be aware of in the Java security framework: Key Manager, Trust Manager and Key Store.

A Key Manager is used by a peer to manage its certificates. This means that in a session set-up, the Key Manager will control which certificates to send to the remote peer.

A Trust Manager is used by a peer to manage remote certificates. This means that in a session set-up, the Trust Manager will control which certificates are trusted from a remote peer.

A Key Store is a Java encapsulation of certificates. Java needs all certificates to either be converted into a Java specific binary format or to be in the PKCS#12 format. These formats are managed using the Key Store class. For the server certificate, we'll use the Java binary format, but for client key/certificate pair, we'll use the PKCS#12 format.

Connecting without validating certificates

Our first example will show a simple client, connecting to a RabbitMQ server over SSL without validating the server certificate, and without presenting any client certificate.

import java.io.*;
import java.security.*;


import com.rabbitmq.client.*;

public class Example1
{
    public static void main(String[] args) throws Exception
    {

	ConnectionFactory factory = new ConnectionFactory();

	factory.useSslProtocol(); // Tells the library to setup the default Key and Trust managers for you

                                  // which do not do any form of remote server trust verification

	Connection conn = factory.newConnection("localhost", 5671);
	Channel channel = conn.createChannel();

	//non-durable, exclusive, auto-delete queue
        channel.queueDeclare("rabbitmq-java-test", false, false, true, true, null);
	channel.basicPublish("", "rabbitmq-java-test", null, "Hello, World".getBytes());


	GetResponse chResponse = channel.basicGet("rabbitmq-java-test", false);
	if(chResponse == null) {
	    System.out.println("No message retrieved");
	} else {
	    byte[] body = chResponse.getBody();
	    System.out.println("Recieved: " + new String(body));
	}


	channel.close();
	conn.close();
    }
}

This simple example is an echo test. It creates a channel rabbitmq-java-test and publishes to the default direct exchange, then reads back what has been published and echoes it out. Note that we use an exclusive, non-durable, auto-delete queue so we don't have to worry about manually cleaning up after ourselves.

Presenting and validating certificates

First, we set-up our Key Store. We'll assume that we have the certificate for the server we want to connect to, so we now need to add it to our Key Store which we will use for the Trust Manager.

# keytool -import -alias server1 -file /path/to/server/cert.pem -keystore /path/to/rabbitstore

The above command will import cert.pem into the rabbitstore and will internally refer to it as server1. The alias argument is used when you have many certificates or keys, as they must all have internally distinct names.

Be sure to answer yes to the question about trusting this certificate, and to pick a passphrase. For this example I set my passphrase to rabbitstore.

We then use our client certificate and key in a PKCS#12 file as already shown above.

Our next example will be a modification of the previous one, to now use our Key Store with our Key Manager and Trust Manager

  import java.io.*;
  import java.security.*;
  import javax.net.ssl.*;

  import com.rabbitmq.client.*;


  public class Example2
  {
      public static void main(String[] args) throws Exception
      {

	char[] keyPassphrase = "MySecretPassword".toCharArray();
	KeyStore ks = KeyStore.getInstance("PKCS12");
	ks.load(new FileInputStream("/path/to/client/keycert.p12"), keyPassphrase);

	KeyManagerFactory kmf = KeyManagerFactory.getInstance("SunX509");
	kmf.init(ks, passphrase);

	char[] trustPassphrase = "rabbitstore".toCharArray();  
	KeyStore tks = KeyStore.getInstance("JKS");
	tks.load(new FileInputStream("/path/to/trustStore"), trustPassphrase);

	TrustManagerFactory tmf = TrustManagerFactory.getInstance("SunX509");
	tmf.init(tks);

	SSLContext c = SSLContext.getInstance("SSLv3");
	c.init(kmf.getKeyManagers(), tmf.getTrustManagers(), null);

	ConnectionFactory factory = new ConnectionFactory();
	factory.useSslProtocol(c);

	Connection conn = factory.newConnection("localhost", 5671);
	Channel channel = conn.createChannel();

	channel.queueDeclare("rabbitmq-java-test", false, false, true, true, null);
	channel.basicPublish("", "rabbitmq-java-test", null, "Hello, World".getBytes());


	GetResponse chResponse = channel.basicGet("rabbitmq-java-test", false);
	if(chResponse == null) {
	    System.out.println("No message retrieved");
	} else {
	    byte[] body = chResponse.getBody();
	    System.out.println("Recieved: " + new String(body));
	}


	channel.close();
	conn.close();
    }
}

To ensure that the above code works in the other case, try setting up your RabbitMQ server with a certificate that has not been imported into the key store and watch the verification exceptions decorate your screen.

RFC 5280, Certificate Key Usage and Mono

As mentioned above, Mono is rather more stringent than is normal about enforcing that certificates are only used for the purposes indicated by the certificate itself.

SSL certificate and keys can be used for a variety of purposes, for example, email signing, code signing, traffic encryption, etc. (For our purposes, we're interested in TCP Traffic encryption). RFC 5280 specifies a number of different purposes, and allows a certificate to be signed for a specific set of purposes.

SSL v3 certificates can contain a number of different extensions. The extension that deals with how a certificate can be used is call the Key Usage Extension. The various usages permitted are not, in general, well supported, or even well defined, and their usage is subject to wide interpretation. Some of the key usages have been deprecated, and mainly, they're just totally ignored.

There is a further extension, which also specifies usages, but chooses to do so using O.I.Ns, such as "1.3.6.1.5.5.7.3.1". Clearly English is lacking something that apparently random numbers add. This is the Extended Key Usage extension - a sequence of object identifiers that further defines which uses of the certificate are permissible.

Mono, however, seems to think that these extensions are both important, and need to be observed. Mono chooses to invalidate the certificate if the certificate omits a Key Usage Extension. By default, OpenSSL omits the Key Usage Extension for self-signed certificates because it is expected that if no Key Usage Extension is found, the certificate is valid to be used for any purpose.

This is the reason why in the sample openssl.cnf file listed above, the extensions specified for root_ca_extensions, client_ca_extensions and server_ca_extensions all have keyUsage specified, and the lacodeer two also have extendedKeyUsage defined. Thus the certificates generated above are valid for use by Mono; keyEncipherment specifies that the certificate can be used by an SSL Server, and digitalSignature specifies that the certificate can be used by an SSL client. The values in the extendedKeyUsage fields precodey much just say the same thing.

You can use this small tool to check that the certificate presented by the RabbitMQ server is acceptable to Mono (note, you'll need to convert the server/cert.pem to server/cert.cer using the OpenSSL command above):

# mono certcheck.exe /path/to/server/cert.cer 
Checking if certificate is SSLv3... Ok
Checking for KeyUsageExtension (2.5.29.15)... Ok
Checking if KeyEncipherment flag is set... Ok
This certificate CAN be used by Mono for Server validation

Who do you say you are?

On the .NET platform, by default the hostname of the server you're connecting to needs to match the CN (Common Name) field on the server's certificate, otherwise the certificate will be rejected. This is why the commands at the start of this guide specify ...-subj /CN=$(hostname)/... which dynamically looks up your hostname. If you're generating certificates on one machine, and using them on the other then be sure to swap out the $(hostname) section, and replace it with the correct hostname for your server.

To suppress the match check, an application can set the System.Net.Security.SslPolicyErrors.RemoteCertificateNameMismatch flag in SslOptions.AcceptablePolicyErrors.

Trust .Net

On the .NET platform, remote certificates are managed by putting them into any of a number of Stores. All management of these stores is done with the 'certmgr' tool which is available on both Microsoft's .Net implementation and on Mono.

NB: On some flavours of Windows there are two versions of the command - one that ships with the operating system and provides a graphical interface only, and one that ships with the .NET Framework Tools and provides both a graphical and command line interface. Either will do the job, but the examples below are based on the latter.

For our case, because we're supplying the client certificate/key pair in a separate PKCS #12 file, all we need to do is to import the certificate of the root Certificate Authority into the Root (Windows) / Trust (Mono) store. All certificates signed by any certificate in that store are automatically trusted.

In contrast to the Java client, which is happy to use an SSL connection without verifying the server's certificate, the .NET client by default requires this verification to succeed. To suppress verification, an application can set the System.Net.Security.SslPolicyErrors.RemoteCertificateNotAvailable and System.Net.Security.SslPolicyErrors.RemoteCertificateChainErrors flags in SslOptions.AcceptablePolicyErrors.

Certificate Management with Certmgr

certmgr allows us to Add, Delete, List and perform other actions on a specified Store. These stores can be per-user stores, or machine wide. Only admin users can have write access to the machine wide stores.

To add a certificate to the users Root (Windows) / Trust (Mono) store we run:

(Windows) # certmgr -add -all \path\to\cacert.cer -s Root
(Mono)    # certmgr -add -c Trust /path/to/cert.cer

To add a certificate to the machine wide store instead we run

(Windows) # certmgr -add -all \path\to\cacert.cer -s -r localMachine Root
(Mono)    # certmgr -add -c -m Trust /path/to/cert.cer

After adding to a store, we can view the contents of that store with the -list switch:

(Windows) # certmgr -all -s Root
(Mono)    # certmgr -list -c Trust

Mono Certificate Manager - version 2.4.0.0
Manage X.509 certificates and CRL from stores.
Copyright 2002, 2003 Motus Technologies. Copyright 2004-2008 Novell. BSD licensed.

Self-signed X.509 v3 Certificate
  Serial Number: AC3F2B74ECDD9EEA00
  Issuer Name:   CN=MyTestCA
  Subject Name:  CN=MyTestCA
  Valid From:    25/08/2009 14:03:01
  Valid Until:   24/09/2009 14:03:01
  Unique Hash:   1F04D1D2C20B97BDD5DB70B9EB2013550697A05E

As we can see, there is one Self-signed X.509 v3 Certificate in the trust store. The Unique Hash uniquely identifies this certificate in this store. To delete this certificate, use the unique hash:

(Windows) # certmgr -del -c -sha1 1F04D1D2C20B97BDD5DB70B9EB2013550697A05E -s Root
(Mono)    # certmgr -del -c Trust 1F04D1D2C20B97BDD5DB70B9EB2013550697A05E

Mono Certificate Manager - version 2.4.0.0
Manage X.509 certificates and CRL from stores.
Copyright 2002, 2003 Motus Technologies. Copyright 2004-2008 Novell. BSD licensed.

Certificate removed from store.

With these simple steps we can go ahead and add/delete/list our root certificates to the client side store.

Creating The Connection

To create an SSL connection to RabbitMQ, we need to set some new fields in the ConnectionFactory's Parameters field. To make things easier, there is a new Field Parameters.Ssl that acts like a namespace for all the other fields that we need to set. The fields are:

• Ssl.CertPath: This is the path to the client's certificate in PKCS#12 format if your server expects client side verification. This is optional.
• Ssl.CertPassphrase: If you are using a client certificate in PKCS#12 format then it'll probably have a password, which you specify in this field.
• Ssl.Enabled: This is a boolean field that turns SSL support on or off. It is off by default.
• Ssl.ServerName: Remember that .Net expects this to match the CN on the certificate that the server sends over.

Code Snippet

// Other initialization here

ConnectionFactory cf = new ConnectionFactory();

cf.Parameters.Ssl.ServerName = System.Net.Dns.GetHostName();
cf.Parameters.Ssl.CertPath = "/path/to/client/keycert.p12";
cf.Parameters.Ssl.CertPassphrase = "MySecretPassword";
cf.Parameters.Ssl.Enabled = true;

IProtocol proto = Protocols.DefaultProtocol;
IConnection conn = cf.CreateConnection(proto, "localhost", 5671);

IModel ch = conn.CreateModel();

// Continue with channel commands here

Bugs in Mono

When the server asks the client to send a certificate, if the client has no certificates to send, it should (according to various specifications) send back a null certificate. Mono fails to do this. Instead, it blindly carries on, acting as if the server hadn't asked for a certificate at all. Coupled with the bug in new_ssl, mentioned above, this means that with RabbitMQ set to {fail_if_no_peer_cert,true} on Erlang before R13B02, if the .Net client is running under Mono, and does not have a certificate to present, the connection will successfully be established.

Erlang SSL Options

The three important options which must be supplied are:

• The cacertfile option specifies the certificates of the root Certificate Authorities that we wish to implicitly trust.
• The certfile is the client's own certificate in PEM format
• The keyfile is the client's private key file in PEM format.

As with RabbitMQ itself, the verify and fail_if_no_peer_cert options are used in Erlang R13 and onwards to specify what action to take if the server doesn't present a certificate or if we're unable to establish a chain of trust to the server's certificate. In R12B5 and prior, the verify_code option serves the same purpose. Check erl -man new_ssl to make sure you have the right options for your version of Erlang.

Code

Params = #amqp_params
  {port = 5671,
  ssl_options = [{cacertfile, "/path/to/testca/cacert.pem"},
		  {certfile,   "/path/to/client/cert.pem"},
		  {keyfile,    "/path/to/client/key.pem"},
		  {verify, verify_peer}, {fail_if_no_peer_cert, true}]},
Conn = amqp_connection:start_network(Params).

You can now go ahead and use Conn as a normal connection.