In some cases it is desirable to ensure no-one but the intended recipient(s) of a message will be able to read its contents. Using SSL/TLS to encrypt traffic travelling between client and broker only ensures that those snooping the network cannot read messages, however once the message arrives at the broker it is decrypted and so anyone with access to the broker can read the message. For such confidential information it is necessary to implement a mechanism of end-to-end encryption such that the sender of the message encrypts the message before sending, and the recipient(s), upon receiving the message, decrypt it with some secret known only to them. Neither JMS nor AMQP provide any defined mechanism for message encryption, however it is possible for any application to build a message encryption scheme on top of a JMS API. For convenience the Client provides a built in mechanism for encryption and decrypting messages. This mechanism is currently only implemented in the Client for AMQP 0-8/0-9/0-9-1/0-10. If you use a different client you will be unable to read encrypted messages.

For each encrypted message which the client sends, a new message-specific secret key is generated. This secret key is used encrypt the message contents using symmetric encryption (currently only AES-256 is supported, although other algorithms may be added at a later date). For each intended recipient of the message, the client encrypts the secret key using the public key associated with the recipient, and adds this as a message header. On receipt of an encrypted message, the client looks to see if it has a private key which can decrypt the secret key. If the client is unable to decrypt the message (for instance, because they were not one of the intended recipients) then the message will be presented to the application as a BytesMessage containing the encrypted data. In order to send an encrypted message it is necessary to know the Certificates of the intended recipients. Certificates can be distributed either through out-of-band mechanisms, or the Apache Qpid Broker for Java can be used to distribute them to clients. In order to receive an encrypted message it is necessary to have a Certificate (which needs to be distributed to those who you wish to send messages to you) and to have the private key associated with the certificate so that you can decrypt messages sent to you.

In order for a connection to be capable of sending encrypted messages, it must be provided with a trust store which contains the X509 certificates of the entities to which you wish to send. The details of the trust store are supplied in the connection URL. There are two distinct mechanisms for providing the encryption trust store. Firstly you can supply a standard password-protected trust store file on the file system. The location and password for this must be specified using the encryption_trust_store and encryption_trust_store_password options respectively. Such a connection URL might look somthing like: amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672?encryption_trust_store='/home/qpid/certificates.jks'&encryption_trust_store_password='password'' Alternatively, where available, you can configure the broker to distribute certificates from a trust store (this is currently only available in the Apache Qpid Broker for Java). In order to use this method, the broker details in the connection url must contain the correctly configured encryption_remote_trust_store option. Such a connection URL might look somthing like: amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672?encryption_remote_trust_store='$certificates%255c/certstore'' The $certificates/ prefix is mandatory. However, in order to prevent the client from interpreting this the wrong way several layers of escaping and encoding need to take place. The slash character ('/') needs to be escaped by a backslash ('\') which needs to be doubly URL encoded resulting in $certificates%255c/. Note that to use the broker-distributed certificates the broker must be configured to expose the trust store as a message source. See the broker documentation on TrustStores for more details.

Message encryption can be enabled individually on each sent message, or - using configuration - all messages sent to a Destination can be encrypted. In order to encrypt messages on a case by case basis, the appliation must set the boolean property x-qpid-encrypt to true on the message before sending. The intended recipients of the message must also be set (see Choosing Recipients). message.setBooleanProperty("x-qpid-encrypt", true); In order to encrypt all messages sent to a given Destination, the option sendencrypted can be used. Note that enabling encryption on the address can be overridden by explicitly setting the property x-qpid-encrypt to false on an individual message. An example address would look like: direct:///queue/queue?sendencrypted='true'

Any message which is to be sent encrypted must also have a list of recipients who the sender wishes to be able to decrypt the message. The recipients must be encoded as a semi-colon separated list of the names given in the respective certificates of the recipients, e.g. cn=first@example.org,ou=example,o=example,l=ny,st=ny,c=us;cn=second@example.org,ou=example,o=example,l=ny,st=ny,c=us. As with enabling encryption, the recipients can be set either on a per-message basis or for all messages sent to a given address. If both forms are used, the former overrides the latter. To set on an individual message, set the String property x-qpid-encrypt-recipients. message.setStringProperty("x-qpid-encrypt-recipients", "cn=only@example.org,ou=example,o=example"); To set the recipients on an address, use the address option encryptedrecipients. direct:///queue/queue?sendencrypted='true'&encryptedrecipients='cn=another@example.org,ou=example,o=example'

Message Encryption encrypts the message content and the properties set by the application. Sometimes it is important to expose properties to allow (for example) message routing or message selectors within the broker to work. To enable this it is possible to specify for each message all the properties which the application wishes to make available to the broker. Note that exposing properties in this way means that they are now visibe to anyone who can inspect the broker memory or file system stores. To make message properties visible to the broker, set the String property x-qpid-unencrypted-properties with a semi-colon separated list of the names of the properties to be exposed. message.setStringProperty("x-qpid-unencrypted-properties", "foo;bar;baz");

In order for a connection to be capable of decrypting received encrypted messages, it must be provided with a key store which contains the X509 certificates and associated Private Keys of the identities on behalf of which it will be able to decrypt. The details of the key store are supplied in the connection URL. The location and password for this must be specified using the encryption_key_store and encryption_trust_store_password options respectively. Such a connection URL might look somthing like: amqp://username:password@clientid/test?brokerlist='tcp://localhost:5672?encryption_key_store='/home/qpid/identities.jks'&encryption_key_store_password='password''

In this example we will setup the Qpid Broker for Java and two clients who will send each other encrypted messages. The clients will use self signed certificates and the certificates will be distributed by the Broker.

For this example it is assumed the Broker is already running and that Management is enabled on port 8443. The example requires two (one for each client) self-signed X.509 certificates and the corresponding keys. We refer to these as client_1/2.cert and client_1/2.key throughout the text below. The following openssl commands can be used to generate self signed certicates suitable for this test.

In this example we want the broker to distribute the client certificates. Essentially, we want the broker to act as a Key Server. Use java's keytool to create a trust store containing the two client certificates. Now a FileTrustStore can be created on the broker pointing to the java trust store that was just created. This can be done via the Web Management Console or the REST API: curl -v -u admin https://localhost:8443/api/v6.1/truststore/clientcerts -X PUT -d '{"type": "FileTrustStore", "stroeUrl": "<path_to_truststore>", "password": "<your_truststore_password>"}' The TrustStore must be configured to expose the certificates as a message source to the clients: curl -v -u admin https://localhost:8443/api/v6.1/truststore/clientcerts -X POST -d '{"exposedAsMessageSource": true}'

The configuration for the clients happens in the connection URL. In this example this is provided via a JNDI properties file. On the producing side, in order to encrypt a message for a recipient, the Qpid client needs the recipient's public certificate which is distributed by the Broker following our above broker setup. The encryption_remote_trust_store element within the connection URL provides the name of the truststore. On the receiving side, in order to decrypt a message it needs a JKS keystore with the private key matching the public certificate. For this example, the keystores can again be created with a two-step process involving openssl and java's keytool. The final JNDI properties file should look similar to this: java.naming.factory.initial = org.apache.qpid.jndi.PropertiesFileInitialContextFactory # connection factories. This is where end-to-end encryption is configured on the client. # connectionfactory.[jndiname] = [ConnectionURL] connectionfactory.producerConnectionFactory = amqp://<username>:<password>@?brokerlist='tcp://localhost:5672?encryption_remote_trust_store='$certificates%255c/clientcerts'' connectionfactory.consumer1ConnectionFactory = amqp://<username>:<password>@?brokerlist='tcp://localhost:5672?encryption_key_store='path/to/client_1.jks'&encryption_key_store_password='<keystore_password>'' connectionfactory.consumer2ConnectionFactory = amqp://<username>:<password>@?brokerlist='tcp://localhost:5672?encryption_key_store='path/to/client_2.jks'&encryption_key_store_password='<keystore_password>'' # Rest of JNDI configuration. For example # destination.[jniName] = [Address Format] queue.myTestQueue = testQueue

On the producing side, the application needs to enable encryption and indicate the intended recipient(s) of each message. This is done via the x-qpid-encrypt and x-qpid-encrypt-recipients message properties. Note that the order of the relative distinguished name (RDN) entries within the recipent's distinguished name (DNs) is significant. If the order does not match that recorded in truststore, a CertificateException will be encountered. On the receiving side, there is nothing to do. The application code does not have to add decryption code as this is handled transparently by the Qpid client library. However, the receiving application should gracefully handle failures in decryption in which case the encrypted message will be delivered as a BytesMessage. // imports omitted for brevity public class EncryptionExample { public EncryptionExample() { } public static void main(String[] args) throws Exception { EncryptionExample encryptionExampleApp = new EncryptionExample(); encryptionExampleApp.runProducerExample(); encryptionExampleApp.runReceiverExample(); } private void runProducerExample() throws Exception { Connection connection = createConnection("producerConnectionFactory"); try { Session session = connection.createSession(true, Session.SESSION_TRANSACTED); Destination destination = createDesination("myTestQueue"); MessageProducer messageProducer = session.createProducer(destination); TextMessage message = session.createTextMessage("Hello world!"); // ============== Enable encryption for this message ============== message.setBooleanProperty("x-qpid-encrypt", true); // ============== Configure recipients for encryption ============== message.setStringProperty("x-qpid-encrypt-recipients", "CN=client1, OU=Qpid, O=Apache, C=US"); messageProducer.send(message); session.commit(); } finally { connection.close(); } } private void runReceiverExample() throws Exception { Connection connection = createConnection("consumer1ConnectionFactory"); try { connection.start(); Session session = connection.createSession(true, Session.SESSION_TRANSACTED); Destination destination = createDesination("myTestQueue"); MessageConsumer messageConsumer = session.createConsumer(destination); Message message = messageConsumer.receive(); if (message instanceof TextMessage) { // application logic System.out.println(((TextMessage) message).getText()); } else if (message instanceof BytesMessage) { // handle potential decryption failure System.out.println("Potential decryption problem. Application not in list of intended recipients?"); } session.commit(); } finally { connection.close(); } } /////////////////////////////////////// // The following is boilerplate code // /////////////////////////////////////// private Connection createConnection(final String connectionFactoryName) throws JMSException, IOException, NamingException { try (InputStream resourceAsStream = this.getClass().getResourceAsStream("example.properties")) { Properties properties = new Properties(); properties.load(resourceAsStream); Context context = new InitialContext(properties); ConnectionFactory connectionFactory = (ConnectionFactory) context.lookup(connectionFactoryName); final Connection connection = connectionFactory.createConnection(); context.close(); return connection; } } private Destination createDesination(String desinationJndiName) throws IOException, NamingException { try (InputStream resourceAsStream = this.getClass().getResourceAsStream("example.properties")) { Properties properties = new Properties(); properties.load(resourceAsStream); Context context = new InitialContext(properties); Destination destination = (Destination) context.lookup(desinationJndiName); context.close(); return destination; } } }