Using TLS with Ruby amqp gem

This Documentation Has Moved to rubyamqp.info

amqp gem documentation guides are now hosted on rubyamqp.info.

About this guide

This guide covers connection to AMQP brokers using TLS (also known as SSL) and related issues. This guide does not explain basic TLS concepts. For that, refer to resources like Introduction to SSL or Wikipedia page on TLS.

Covered versions

This guide covers Ruby amqp gem v0.8.0 and later.

Broker version requirements

RabbitMQ

RabbitMQ supports TLS since version 1.7.0. Minimum requirements are

• Erlang R13B
• Erlang SSL application 3.10

The recommended distribution is R14B (SSL 4.0.1) or later. This should be considered the minimum configuration for Java and Erlang clients due to an incorrect RC4 implementation in earlier versions of Erlang.

Learn more at rabbitmq.com TLS page.

Pre-requisites

AMQP brokers typically need to be configured to use TLS. Just like Web servers, TLS connections are usually accepted on a separate port (5671). rabbitmq.com TLS page describes how to configure RabbitMQ to use TLS, how to generate certificates for development and so on.

Connecting to AMQP broker using TLS

To instruct Ruby amqp gem to use TLS for connection, pass :ssl option that specifies certificate chain file path as well as private key file path:

AMQP.start(:port     => 5671,
           :ssl => {
             :cert_chain_file  => certificate_chain_file_path,
             :private_key_file => client_private_key_file_path
           }) do |connection|
  puts "Connected, authenticated. TLS seems to work."

  connection.disconnect { puts "Now closing the connection…"; EventMachine.stop }
end

Note that TLS connection may take a bit of time to establish (up to several seconds in some cases). To verify that broker connection actually uses TLS, refer to RabbitMQ log file:

=INFO REPORT==== 28-Jun-2011::08:41:24 ===
accepted TCP connection on 0.0.0.0:5671 from 127.0.0.1:53444

=INFO REPORT==== 28-Jun-2011::08:41:24 ===
starting TCP connection <0.9904.0> from 127.0.0.1:53444

=INFO REPORT==== 28-Jun-2011::08:41:24 ===
upgraded TCP connection <0.9904.0> to SSL

Example code

TLS example (as well as sample certificates you can use to get started with) can be found in the amqp gem git repository

Authors

This guide was written by Michael Klishin and edited by Chris Duncan.

Tell us what you think!

Please take a moment and tell us what you think about this guide on Twitter or Ruby AMQP mailing list: what was unclear? what wasn’t covered? maybe you don’t like guide style or grammar and spelling are incorrect? Readers feedback is key to making documentation better.

If mailing list communication is not an option for you for some reason, you can contact guides author directly