# @title Ruby AMQP gem: Using TLS

h1. Using TLS with Ruby amqp gem

h2. This Documentation Has Moved to rubyamqp.info

amqp gem documentation guides are now hosted on "rubyamqp.info":http://rubyamqp.info.


h2. 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":https://developer.mozilla.org/en/Introduction_to_SSL
or "Wikipedia page on TLS":http://en.wikipedia.org/wiki/Transport_Layer_Security.


h2. Covered versions

This guide covers "Ruby amqp gem":http://github.com/ruby-amqp/amqp v0.8.0 and later.


h2. Broker version requirements

h3. 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":http://www.rabbitmq.com/ssl.html.



h2. 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":http://www.rabbitmq.com/ssl.html describes how to configure RabbitMQ
to use TLS, how to generate certificates for development and so on.



h2. 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:

<pre>
<code>
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
</code>
</pre>

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:

<pre>
=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
</pre>



h2. 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":https://github.com/ruby-amqp/amqp/tree/master/examples


h2. Authors

This guide was written by "Michael Klishin":http://twitter.com/michaelklishin and edited by "Chris Duncan":https://twitter.com/celldee.



h2. Tell us what you think!

Please take a moment and tell us what you think about this guide "on Twitter":http://twitter.com/rubyamqp or "Ruby AMQP mailing list":http://groups.google.com/group/ruby-amqp:
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":mailto:michael@novemberain.com?subject=amqp%20gem%20documentation