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-J). 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");