Document TLS/SSL support

[edmorley]

PR #446 added support for TLS, however it's currently undocumented.

I'm trying to add documentation/support for TLS to consumers of redis-py (eg django-redis/django-redis-cache), however this is harder when there isn't upstream documentation to refer to :-)

[edmorley]

The various ways to use TLS with redis-py seem to be:

1. Using arguments to the client constructor:

r = redis.StrictRedis(
    host='HOSTNAME',
    port=NNNN,
    password='PASSWORD',
    ssl=True,
    # optional:
    ssl_cert_reqs='required',
    ssl_ca_certs='/path/to/custom/ca-cert',
)

2. Using StrictRedis.from_url() and the rediss:// scheme (plus optional query-string params):

redis_url = 'rediss://h:PASSWORD@HOSTNAME:NNNN?ssl_cert_reqs=required&ssl_ca_certs=/path/to/custom/ca-cert'
r = redis.StrictRedis.from_url(redis_url)

3. Creating a connection pool with a connection class of SSLConnection:

pool = redis.ConnectionPool(
    host='HOSTNAME',
    port=NNNN,
    password='PASSWORD',
    connection_class=redis.SSLConnection,
    # optional:
    ssl_cert_reqs='required',
    ssl_ca_certs='/path/to/custom/ca-cert',
)
r = redis.StrictRedis(connection_pool=pool)

4. Creating a connection pool using ConnectionPool.from_url():

redis_url = 'rediss://h:PASSWORD@HOSTNAME:NNNN?ssl_cert_reqs=required&ssl_ca_certs=/path/to/custom/ca-cert'
pool = redis.ConnectionPool.from_url(redis_url)
r = redis.StrictRedis(connection_pool=pool)

There are also a couple of typos in the changelog entry:
https://github.com/andymccurdy/redis-py/blob/b40875d553ab6d6db69e64eef134e5fac652b033/CHANGES#L110-L114
"sll=True" -> "ssl=True"
"and SSL connection" -> "an SSL connection"

[taion]

I just hit this. If someone can point me at the correct section in the docs to update, I can write up the docs update.

[github-actions]

This issue is marked stale. It will be closed in 30 days if it is not updated.

[taion]

I'm still happy to write this up if I can get some pointers on which doc to update.

[RoeyPrat]

a PR to fix the typos mentioned: #1362

[RoeyPrat]

@taion The documentation is generated from index.rst and the docstrings of the callable objects.
Any documentation about a specific object should be documented in its docstring, but if there is general documentation that doesn't belong to any specific object, perhaps it should be added to index.rst as a section.

[taion]

Hmm, so I actually have no idea what's missing in the docs. The use of rediss:// appears to be documented, and the README explains the use of ssl_cert_reqs with ElastiCache: https://github.com/andymccurdy/redis-py/blob/1870c26fecb44281e451cab3185f8a566fc75b0f/README.rst#ssl-connections.

As far as I can tell, then, everything I would have needed back when I commented on this issue initially is now there. Maybe this can be closed out?

[aiguofer]

I spent hours trying to figure out how the hell to get SSL to work when using a ConnectionPool. I tried passing ssl=True to the ConnectionPool but that was a no go. I tried passing ssl=True to the StrictRedis instantiation, and that didn't do anything. When I look at the docs for the ConnectionPool class, it doesn't mention anything about SSL (sure, it does mention you can specify the class, but I didn't know there's a SSLConnection).

Finally finding this issue helped me figure it out. So... to answer "what's missing in the docs", I would say the examples from #780 (comment) would be a great addition.

[CharlaftisBill]

I am trying to connect to redis using username, password and ssl.
when I use the following code :

pool = redis.ConnectionPool.from_url("rediss://"+username+":"+password+"@"+ip+":"+port+"?ssl_cert_reqs=required")
redisConnection = redis.StrictRedis(connection_pool=pool)

Then an error like this is been raised:

Traceback (most recent call last):
  .
  .
  .
ValueError: Port could not be cast to integer value as 'password_value'

In my understanding there is a bug while the url string is been cut to make port sub string.

The ACL users has been made using this doc:

• https://redis.io/topics/acl

And the connection has been using both redis-cli (and AUTH) and a Node.js app (Node Redis lib).

I am feeling really confused because redis.StrictRedis and redis.Redis have no username argument to them constructors but if you dive a little deeper in lib code you can find that there is place for it (for example: in redis.Connection and redis.ConnectionPool).

Could you please help me point out what exactly I am doing wrong?

[abhinavsingh]

Incredible, open since 2016 and still attracting visitors in 2021.

This issue has now truly graduated.

[tan-i-ham]

The various ways to use TLS with redis-py seem to be:

1. Using arguments to the client constructor:

r = redis.StrictRedis(
    host='HOSTNAME',
    port=NNNN,
    password='PASSWORD',
    ssl=True,
    # optional:
    ssl_cert_reqs='required',
    ssl_ca_certs='/path/to/custom/ca-cert',
)

2. Using StrictRedis.from_url() and the rediss:// scheme (plus optional query-string params):

redis_url = 'rediss://h:PASSWORD@HOSTNAME:NNNN?ssl_cert_reqs=required&ssl_ca_certs=/path/to/custom/ca-cert'
r = redis.StrictRedis.from_url(redis_url)

3. Creating a connection pool with a connection class of SSLConnection:

pool = redis.ConnectionPool(
    host='HOSTNAME',
    port=NNNN,
    password='PASSWORD',
    connection_class=redis.SSLConnection,
    # optional:
    ssl_cert_reqs='required',
    ssl_ca_certs='/path/to/custom/ca-cert',
)
r = redis.StrictRedis(connection_pool=pool)

4. Creating a connection pool using ConnectionPool.from_url():

redis_url = 'rediss://h:PASSWORD@HOSTNAME:NNNN?ssl_cert_reqs=required&ssl_ca_certs=/path/to/custom/ca-cert'
pool = redis.ConnectionPool.from_url(redis_url)
r = redis.StrictRedis(connection_pool=pool)

There are also a couple of typos in the changelog entry: https://github.com/andymccurdy/redis-py/blob/b40875d553ab6d6db69e64eef134e5fac652b033/CHANGES#L110-L114 "sll=True" -> "ssl=True" "and SSL connection" -> "an SSL connection"

I have successfully connected by this way

pool = redis.ConnectionPool(
    host='HOSTNAME',
    port=NNNN,
    password='PASSWORD',
    connection_class=redis.SSLConnection,
)
r = redis.Redis(connection_pool=pool, ssl=True)
r.ping() # True

in case someone might meet the same problem, hope it will help!

[chayim]

While not everything has been documented - we just merged in documentation and some examples (#1835) - including SSL. Those examples now publish to readthedocs, and are generated from jupyter notebooks.

If you're able to, please help expand upon them!

[jdubs11]

• How do you configure what ciphers to be used?
• Why aren't the OS default ca certificates used when not specifying a ca cert file?
• Why can't I just pass an ssl.SSLContext object to the factory functions? I can't even pass one to the constructor -- "cannot pickle ssl.SSLContext object"

You have some pretty good docs on OCSP stapling, but if I don't do that then docs and functionality seem pretty weak for any kind of TLS configuration settings. I can't even specify a minimum protocol to be used?

I have been trying to figure out how to "properly" configure TLS settings in this library for far too long (longer than a single work day) so any help here is appreciated :)

[chayim]

@sav-norem. Wanna?

[chayim]

@nermiller maybe you're interested?

[github-actions]

This issue is marked stale. It will be closed in 30 days if it is not updated.