Detailed more on BROKER_USE_SSL, especially the dict-form

CONTRIBUTORS.txt

@@ -180,3 +180,13 @@ Bert Vanderbauwhede, 2014/12/18
 John Anderson, 2014/12/27
 Luke Burden, 2015/01/24
 Mickaël Penhard, 2015/02/15
+Mark Parncutt, 2015/02/16
+Samuel Jaillet, 2015/03/24
+Ilya Georgievsky, 2015/03/31
+Fatih Sucu, 2015/04/17
+James Pulec, 2015/04/19
+Alexander Lebedev, 2015/04/25
+Frantisek Holop, 2015/05/21
+Feanil Patel, 2015/05/21
+Jocelyn Delalande, 2015/06/03
+Juan Rossi, 2015/08/10

docs/configuration.rst

@@ -999,9 +999,40 @@ will be performed every 5 seconds (twice the heartbeat sending rate).
 
 BROKER_USE_SSL
 ~~~~~~~~~~~~~~
+:transports supported: ``pyamqp``
+
+
+Toggles SSL usage on broker connection and SSL settings.
+
+If ``True`` the connection will use SSL with default SSL settings.
+If set to a dict, will configure SSL connection according to the specified
+policy. The format used is python `ssl.wrap_socket()
+options <https://docs.python.org/3/library/ssl.html#ssl.wrap_socket>`_.
+
+Default is ``False`` (no SSL).
+
+Note that SSL socket is generally served on a separate port by the broker.
+
+Example providing a client cert and validating the server cert against a custom
+certificate authority:
+
+.. code-block:: python
+
+    import ssl
+
+    BROKER_USE_SSL = {
+      'keyfile': '/var/ssl/private/worker-key.pem',
+      'certfile': '/var/ssl/amqp-server-cert.pem',
+      'ca_certs': '/var/ssl/myca.pem',
+      'cert_reqs': ssl.CERT_REQUIRED
+    }
+
+.. warning::
 
-Use SSL to connect to the broker.  Off by default.  This may not be supported
-by all transports.
+    Be careful using ``BROKER_USE_SSL=True``, it is possible that your default
+    configuration do not validate the server cert at all, please read Python
+    `ssl module security
+    considerations <https://docs.python.org/3/library/ssl.html#ssl-security>`_.
 
 .. setting:: BROKER_POOL_LIMIT