This guide covers TLS (SSL) connections to RabbitMQ with Bunny.
This work is licensed under a Creative Commons Attribution 3.0 Unported License (including images and stylesheets). The source is available on Github.
This guide covers Bunny 2.10.x and later versions.
RabbitMQ version 3.x supports TLS/SSL on Erlang R16B03 or later. Using the most recent version (e.g. 17.1 or 17.1) is recommended.
To use TLS with RabbitMQ, you need a few things:
The easiest way to generate a CA, server and client keys and certificates is by using tls-gen. It requires openssl and make to be available.
See RabbitMQ TLS/SSL guide for more information about TLS support on various platforms.
TLS/SSL support is enabled using two arguments:
ssl_listeners (a list of ports TLS connections will use)ssl_options (a proplist of options such as CA certificate file location, server key file location, and so on)An example that requires client certificate and performs client authentication:
[ {rabbit, [ {ssl_listeners, [5671]}, {ssl_options, [{cacertfile,"/path/to/testca/cacert.pem"}, {certfile,"/path/to/server/cert.pem"}, {keyfile,"/path/to/server/key.pem"}, {verify,verify_peer}, {fail_if_no_peer_cert,true}]} ]} ]. An example that requires no client certificate and performs no authentication (not recommended for production):
[ {rabbit, [ {ssl_listeners, [5671]}, {ssl_options, [{cacertfile,"/path/to/testca/cacert.pem"}, {certfile,"/path/to/server/cert.pem"}, {keyfile,"/path/to/server/key.pem"}, {verify,verify_none}, {fail_if_no_peer_cert,false}]} ]} ]. Note that all paths must be absolute (no ~ and other shell-isms) and be readable by the OS user RabbitMQ uses.
Learn more in the RabbitMQ TLS/SSL guide.
There are several options Bunny.new takes:
:tls which, when set to true, will set SSL context up and switch to TLS port (5671):tls_cert which is a string path to the client certificate (public key) in PEM format:tls_key which is a string path to the client key (private key) in PEM format:tls_ca_certificates which is an array of string paths to CA certificates in PEM format:verify_peer which determines if TLS peer authentication (verification) is performed, true by defaultAn example:
conn = Bunny.new(:tls => true, :tls_cert => "examples/tls/client_cert.pem", :tls_key => "examples/tls/client_key.pem", :tls_ca_certificates => ["./examples/tls/cacert.pem"], # convenient for dev/QA, please enable in production :verify_peer => false) If you configure RabbitMQ to accept TLS connections on a separate port, you need to specify both :tls and :port options:
conn = Bunny.new(:tls => true, # custom port RabbitMQ TLS listener is configured to use :port => 6778, :tls_cert => "examples/tls/client_cert.pem", :tls_key => "examples/tls/client_key.pem", :tls_ca_certificates => ["./examples/tls/cacert.pem"], # convenient for dev/QA, please enable in production :verify_peer => false) Paths can be relative but it's recommended to use absolute paths and no symlinks to avoid issues with path expansion.
In cases when reading files from the filesystem is not an option, it is possible to provide certificates and keys inline:
cert = <<-EOS -----BEGIN CERTIFICATE----- MIIC8zCCAdugAwIBAgIBATANBgkqhkiG9w0BAQUFADAiMREwDwYDVQQDEwhNeVRl c3RDQTENMAsGA1UEBxMEMTgxNTAeFw0xMzA2MDIxNTU0MDBaFw0xNDA2MDIxNTU0 MDBaMCcxFDASBgNVBAMTC2dpb3ZlLmxvY2FsMQ8wDQYDVQQKEwZjbGllbnQwggEi MA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDj70Z3cs873uTdONh/gK0vEI75 okTHOQBz9QPVUx0c+cdUvp1Ct1FXBYM4Jq47aaRW5vuki0SeML0gdrQouSVFtblX HnB8bYF1oMlkmTrIDvM9DT5H3AMiQbbypVkRjQBb/Rs97sr+P05jhK2ZWxTxzs3W kqdblJaxfMX7IXgvobnXDJO0PcN7tzOOlcD8dGFABLEtzWRmzqVvrJ7tZh0klsiB I2yuOjk9LZhNcgmSNUAln+MFkWiAQcwWvl77DSBVPqIi6w6Q0oJoS6gsT6jOfw3f ApX7Fjoib3UXLrZC2Fe7Sq03joZcpL7lMqsEZCZr0VqASQJHoTPqEknSMlpxAgMB AAGjLzAtMAkGA1UdEwQCMAAwCwYDVR0PBAQDAgeAMBMGA1UdJQQMMAoGCCsGAQUF BwMCMA0GCSqGSIb3DQEBBQUAA4IBAQCFpfTUD9CjkrlhJi8GrryRlBILah45HIH4 MuUEUaGE//glCTuKXHjUhgtFSkFaDr0Xq50ckUzMVdmsQpSZM3N1F/eTicIk1PzY b+7t86/XC5wct94I5yxPNX7S8VwHtK8yav0WwMwEGmduTxfjMPnJBDPdwIp6LgiF BqM4Hh8HxHdr+MxOg3JGiodM7MMsDs1A05RiBcR3RzMvbXn5eQIy7tHOJMnrdbj9 mOrfKAmRlWyNj3mhOVpae22sbtSxHYZ10b0Xp/KFusiZCfQvo4pERonjUoMLtaPE RtPrRrHy96dzmpVFnDVaA+CKZqyBncVAT0zQ3lIJdFIOEbE//s06 -----END CERTIFICATE----- EOS key = <<-EOS -----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEA4+9Gd3LPO97k3TjYf4CtLxCO+aJExzkAc/UD1VMdHPnHVL6d QrdRVwWDOCauO2mkVub7pItEnjC9IHa0KLklRbW5Vx5wfG2BdaDJZJk6yA7zPQ0+ R9wDIkG28qVZEY0AW/0bPe7K/j9OY4StmVsU8c7N1pKnW5SWsXzF+yF4L6G51wyT tD3De7czjpXA/HRhQASxLc1kZs6lb6ye7WYdJJbIgSNsrjo5PS2YTXIJkjVAJZ/j BZFogEHMFr5e+w0gVT6iIusOkNKCaEuoLE+ozn8N3wKV+xY6Im91Fy62QthXu0qt N46GXKS+5TKrBGQma9FagEkCR6Ez6hJJ0jJacQIDAQABAoIBACfSlCMmYeJ57M5h siGEn71LTU979DxCTzvzILpSjRGU6ih6LQuM758ejXBwAZzLtjSgonJ7CoAAz+ou EwfSYRquxzTbUpfKogWlE8qJouV1BzYxbCIt5DZF+OqnzMnuMpPfwrStVbXZ5Z4p fhL/AMfGc9v7P1YWvcVAoW5gyJi5ejL4az82ZHqDltkkPBm7yXI1xaoAuAU+ir4X AArDQWqqD+lPVD8gtMfyRYek7xL/O2SZUAVNQC14Fi2gmh01FFW/gnPmoT7GutEL gfdEQ1KpyzquaSf1u/cka9jbdqf2fAhMj6UwasIJ1HF8dzblzO/nB+cTzIo9LzoK erwQs2ECgYEA/nTWap6M7InOeAkosEEeLcu0idnjxlT/OToRtfdNkKatvqAFpSDd 2IBzr3kH+qGToeF8B7uJBaWO69m28+yEngWNW1u0KICUTTzlKZqSqNy1nxWnCWVk Eg9LtEja4ncoWufbxBB6wwptk4RSqB9HUeZSQf8CG5MvDCLmEsMwwLUCgYEA5VFA FSZJ3X96nGHlrokq7yDNAQLVZ72B+X+SRt7b9FMVeTyT7fQCAjFSiZYR0Tuz8XEn STARp27K8OyFv0L1ZzHeywRcqICo9Eqa4Q/Juw+Waf3F40f1lxXb09OTHI/JedWz U+VMX/OgsFW4a/3/L+IatlnBKemTKvhd94E5VE0CgYEAsQtcMLz2cpIDrXM580Cr ndORXyTSnamAFzI3JnPWbSH725l9tAIlOUFOvLWqfpEzpju8T6kFUn957NIDwL49 G7HjQ8CPnmqwRPlsvUDGcGV4nSK0oQ4BzasE0oCqg03DL1UJjOamc9Rqn2w/EqkI t4xYiYDD16nV30zc5gsXfc0CgYBLlwvbrOJeXB4rnG2cqeR4LMTG14tHBgXpG285 Y07368dBToGox20+EcoWRlybLuXy6Yy8qFa5bWECJ8Uytby1BpBdNZPhi3+l/02s cIrb2ZiIWbm4YMkIw5DR84UjvhX4zkOtnQEfA+ztE2SWXISY4RxTDaUJzs/PM02u P2+JZQKBgFcOXsnCR/x1CQ6j90pqXjvAK6x/Aiwx0FFTtcPdDft/zuJzav1Co84u vUGvUADy1AVUB5ERz3z6us9gA4tUIeNwlQ0XFQXVT7I7GBXO3eF5PeiCXfThqnm9 dHgVP3fRaFosQv7mQe6BuuUHP3TJwT1qv/cWmiyyc1Xs7L2b4YU/ -----END RSA PRIVATE KEY----- EOS conn = Bunny.new(:tls => true, :tls_cert => cert, :tls_key => key, :tls_ca_certificates => ["./examples/tls/cacert.pem"], # convenient for dev/QA, please enable in production :verify_peer => false) It is possible to use amqps:// URIs in combination with additional options, e.g. to provide TLS certificate and key paths:
c = Bunny.new("amqps://bunny_gem:bunny_password@127.0.0.1/bunny_testbed", :tls_cert => "spec/tls/client_cert.pem", :tls_key => "spec/tls/client_key.pem", :tls_ca_certificates => ["./spec/tls/cacert.pem"], # convenient for dev/QA, please enable in production :verify_peer => false) c.start In some situations it is reasonable to disable peer verification (authentication), which is enabled by default. This means TLS will only be used for encryption and not authentication, enabling man-in-the-middle (MITM) attacks. This is a reasonable thing to do in development but we highly recommend using peer verification in production environments.
To disable peer with Bunny, use :verify_peer:
c = Bunny.new("amqps://bunny_gem:bunny_password@127.0.0.1/bunny_testbed", :tls_cert => "spec/tls/client_cert.pem", :tls_key => "spec/tls/client_key.pem", :tls_ca_certificates => ["./spec/tls/cacert.pem"], :verify_peer => false) c.start When disabling peer verification, make sure RabbitMQ is also configured to not verify peer. In such case, it is possible to forego providing client certificate and private key:
c = Bunny.new("amqps://bunny_gem:bunny_password@127.0.0.1/bunny_testbed", :tls_ca_certificates => ["./spec/tls/cacert.pem"], :verify_peer => false) c.start Disabling peer verification is not recommended for production.
Bunny will use CA certificate paths used by OpenSSL if OpenSSL can provide this information. When using self-signed certificates with a custom certificate authority, it is possible to place CA certificates to a system location.
To detect the location, run the following code in the REPL after loading OpenSSL:
irb -ropenssl ENV[OpenSSL::X509::DEFAULT_CERT_DIR_ENV] || OpenSSL::X509::DEFAULT_CERT_DIR # => "/usr/local/etc/openssl/certs" Bunny will use the following TLS/SSL CA's paths on Linux by default:
/etc/ssl/certs/ca-certificates.crt on Ubuntu/Debian/etc/ssl/certs/ca-bundle.crt on Amazon Linux/etc/ssl/ca-bundle.pem on OpenSUSE/etc/pki/tls/certs/ca-bundle.crt on Fedora/RHELand will log a warning if no CA files are available via default paths or :tls_ca_certificates.
Bunny will use TLSv1 through TLSv1.2 when available, and fall back to insecure SSLv3 if that's the only version supported.
Note that RabbitMQ will reject SSLv3 connections unless configured otherwise, starting with 3.4.0.
POODLE is a known SSL/TLS attack that originally compromised SSLv3. Starting with version 3.4.0, RabbitMQ server refuses to accept SSLv3 connections. In December 2014, a modified version of the POODLE attack that affects TLSv1.0 was announced. It is therefore recommended to disable TLSv1.0 support (see below) when possible.
BEAST attack is a known vulnerability that affects TLSv1.0. To mitigate it, disable TLSv1.0 support (see below).
To limit enabled SSL/TLS protocol versions, use the versions option in RabbitMQ configuration:
%% Disable SSLv3.0 support, leaves TLSv1.0 enabled. [ {ssl, [{versions, ['tlsv1.2', 'tlsv1.1', tlsv1]}]}, {rabbit, [ {ssl_listeners, [5671]}, {ssl_options, [{cacertfile,"/path/to/ca_certificate.pem"}, {certfile, "/path/to/server_certificate.pem"}, {keyfile, "/path/to/server_key.pem"}, {versions, ['tlsv1.2', 'tlsv1.1', tlsv1]} ]} ]} ]. %% Disable SSLv3.0 and TLSv1.0 support. [ {ssl, [{versions, ['tlsv1.2', 'tlsv1.1']}]}, {rabbit, [ {ssl_listeners, [5671]}, {ssl_options, [{cacertfile,"/path/to/ca_certificate.pem"}, {certfile, "/path/to/server_certificate.pem"}, {keyfile, "/path/to/server_key.pem"}, {versions, ['tlsv1.2', 'tlsv1.1']} ]} ]} ]. to verify, use openssl s_client:
# connect using SSLv3 openssl s_client -connect 127.0.0.1:5671 -ssl3 # connect using TLSv1.0 through v1.2 openssl s_client -connect 127.0.0.1:5671 -tls1 and look for the following in the output:
SSL-Session: Protocol : TLSv1 The documentation is organized as a number of guides, covering various topics.
Please take a moment to tell us what you think about this guide on Twitter or the Bunny mailing list
Let us know what was unclear or what has not been covered. Maybe you do not like the guide style or grammar or discover spelling mistakes. Reader feedback is key to making the documentation better.