feat: add TLS session caching support by dkropachev · Pull Request #657 · scylladb/python-driver

dkropachev · 2026-01-29T15:45:27Z

Summary

This PR adds TLS session caching support to the Python driver, enabling faster reconnections by reusing negotiated TLS sessions. This reduces handshake latency for both TLS 1.2 (session IDs/tickets) and TLS 1.3 (session tickets).

Fixes: #426

Changes

Core Implementation:

Add cassandra.tls module with TLSSessionCache abstract base class and DefaultTLSSessionCache implementation featuring LRU eviction, TTL expiration, and periodic cleanup
Add tls_session_cache_key property to endpoint classes (EndPoint, SniEndPoint, UnixSocketEndPoint) for proper cache key generation
Integrate TLS session caching in Connection class - apply cached sessions during wrap_socket() and store sessions after successful connections

Cluster Configuration:

tls_session_cache_enabled: toggle caching on/off (default: True)
tls_session_cache_size: max cached sessions (default: 100)
tls_session_cache_ttl: session TTL in seconds (default: 3600)
tls_session_cache_options: advanced config via TLSSessionCacheOptions or custom TLSSessionCache implementation

Reactor Support:

EventletConnection: TLS session caching via PyOpenSSL's session API
TwistedConnection: TLS session caching via _SSLCreator class

Testing

Unit tests for DefaultTLSSessionCache (TTL, LRU eviction, thread safety, cleanup)
Unit tests for endpoint tls_session_cache_key properties
Unit tests for EventletConnection and TwistedConnection TLS session handling
Integration tests for end-to-end session caching with real clusters

Documentation

Added TLS session caching section to security guide with configuration examples

Pre-review checklist

I have split my patch into logically separate commits.
All commit messages clearly explain what they change and why.
I added relevant tests for new features and bug fixes.
All commits compile, pass static checks and pass test.
PR description sums up the changes and reasons why they should be introduced.
I have provided docstrings for the public items that I want to introduce.
I have adjusted the documentation in ./docs/source/.
I added appropriate Fixes: annotations to PR description.

tests/unit/test_endpoints.py

tests/unit/io/test_eventletreactor.py

Adds cassandra.tls module with: - TLSSessionCache abstract base class defining the caching interface - DefaultTLSSessionCache with LRU eviction, TTL expiration, and periodic cleanup - TLSSessionCacheOptions for configuring cache parameters TLS session caching enables faster reconnections by reusing negotiated TLS sessions, reducing handshake latency for both TLS 1.2 (session IDs/tickets) and TLS 1.3 (session tickets).

Add tls_session_cache_key property to EndPoint, SniEndPoint, and UnixSocketEndPoint classes to provide appropriate cache keys for TLS session caching: - EndPoint: (address, port) - SniEndPoint: (address, port, server_name) to prevent cache collisions when multiple SNI endpoints use the same proxy - UnixSocketEndPoint: (path,) since Unix sockets have no port

Add TLS session caching support to the Connection class: - Add tls_session_cache parameter to Connection.__init__ - Apply cached sessions during wrap_socket() for session resumption - Store sessions after successful connection in _connect_socket() - Support both TLS 1.2 and TLS 1.3 session resumption Sessions are only cached after successful connections to avoid caching sessions from failed connection attempts.

Add TLS session caching configuration options to the Cluster class: - tls_session_cache_enabled: toggle caching on/off (default: True) - tls_session_cache_size: max cached sessions (default: 100) - tls_session_cache_ttl: session TTL in seconds (default: 3600) - tls_session_cache_options: advanced config via TLSSessionCacheOptions or custom TLSSessionCache implementation The cache is automatically created when SSL is enabled and passed to connections via the connection factory.

Implement TLS session caching for the eventlet reactor using PyOpenSSL's session API: - Apply cached session via set_session() before handshake - Store session via get_session() after successful handshake - Log session reuse for debugging

Implement TLS session caching for the Twisted reactor using PyOpenSSL's session API via the _SSLCreator class: - Pass tls_session_cache to _SSLCreator - Apply cached session in clientConnectionForTLS() - Store session in info_callback() after successful handshake - Log session reuse for debugging

Add comprehensive unit tests for DefaultTLSSessionCache: - Basic get/set operations - Multiple endpoints with separate cache entries - TTL expiration - LRU eviction when cache is full - cache_by_host_only mode - Thread safety under concurrent access - Periodic cleanup of expired sessions - Clear operations

Add tests verifying the tls_session_cache_key property for each endpoint type: - DefaultEndPoint returns (address, port) - SniEndPoint includes server_name to prevent cache collisions - UnixSocketEndPoint returns just the path

Add tests for TLS session caching in the eventlet reactor: - Cached session is applied via set_session() - Session is stored after successful handshake - Session reuse is detected and logged - Behavior without cache configured

Add tests for TLS session caching in the Twisted reactor: - Cached session is applied in clientConnectionForTLS() - Session is stored in info_callback() after handshake - Session reuse is detected and logged - _SSLCreator properly receives and uses tls_session_cache

Add integration tests that verify TLS session caching works end-to-end with a real Scylla/Cassandra cluster: - Session caching enabled by default with SSL - Session reuse on reconnection - Cache disabled when tls_session_cache_enabled=False - Custom cache options via TLSSessionCacheOptions

Document the TLS session caching feature in the security guide: - Overview of session resumption benefits - Configuration options (enabled, size, ttl, options) - Advanced configuration with TLSSessionCacheOptions - Custom cache implementation example - Notes on TLS 1.2 vs TLS 1.3 behavior

Lorak-mmk

One additional question: Why did you have to integrate it specifically with eventlet and twisted, while there is already integration in Connection class? And why other reactors don't need that?

cassandra/tls.py

Lorak-mmk · 2026-02-16T12:37:57Z

cassandra/tls.py

+    @abstractmethod
+    def get_session(self, endpoint):
+        """
+        Get a cached TLS session for the given endpoint.
+
+        Args:
+            endpoint: The EndPoint object representing the connection target
+
+        Returns:
+            ssl.SSLSession object if a valid cached session exists, None otherwise
+        """
+        pass


Could you use type hints instead of comments describing the return type?

This applices to all methods, both to args and return types.

Added type hints to all methods in TLSSessionCache and DefaultTLSSessionCache (args and return types). Removed docstring-based type descriptions.

cassandra/tls.py

cassandra/cluster.py

dkropachev · 2026-02-16T14:31:52Z

Addressing review feedback:

Copyright header (cassandra/tls.py): Fixed. Changed to ScyllaDB copyright since this is new code, not backported from upstream.

Type hints: Fixed. Added type hints to all methods in TLSSessionCache and DefaultTLSSessionCache (args and return types). Removed docstring-based type descriptions.

ABC / @abstractmethod: Removed. You're right, it's not used elsewhere in the driver. Switched to a regular base class with raise NotImplementedError — consistent with the existing codebase patterns.

Consolidate Cluster parameters: Done. Replaced the 4 parameters (tls_session_cache_enabled, tls_session_cache_size, tls_session_cache_ttl, tls_session_cache_options) with a single tls_session_cache parameter. Set to None to disable, pass TLSSessionCacheOptions(...) for custom config, or pass a TLSSessionCache subclass instance for full control. Default behavior (auto-create cache when SSL is enabled) is preserved.

Why eventlet/twisted need separate integration: The base Connection class uses Python's built-in ssl module (ssl.SSLContext.wrap_socket()) which returns an ssl.SSLSocket with a .session property for session resumption. EventletConnection and TwistedConnection use PyOpenSSL instead (SSL.Connection), which has a completely different API for session management (get_session()/set_session() methods instead of the .session property). The other reactors (asyncore, libev, asyncio, gevent) all inherit from the base Connection class and use Python's built-in ssl module, so they get the integration for free.

- Fix copyright header: use ScyllaDB instead of DataStax for new files - Remove ABC/abstractmethod from TLSSessionCache, use NotImplementedError - Add type hints to all methods in TLSSessionCache and DefaultTLSSessionCache - Consolidate 4 Cluster parameters into single tls_session_cache parameter (None to disable, TLSSessionCacheOptions for config, TLSSessionCache for custom) - Update docs and tests for new API

Lorak-mmk · 2026-02-16T14:43:24Z

ABC / @AbstractMethod: Removed. You're right, it's not used elsewhere in the driver. Switched to a regular base class with raise NotImplementedError — consistent with the existing codebase patterns.

In my comment I did not ask for the change. I asked for explanation. I don't know the differences between the two approaches, and wanted to understand them. This would allow us to choose better approach, but now I still don't know how they are different.

Lorak-mmk · 2026-02-16T14:45:04Z

Btw, why are you responding here, instead of responding to the comments as usual? It will be much harder to keep track of dicsussions.

dkropachev · 2026-02-16T14:58:22Z

ABC / @AbstractMethod: Removed. You're right, it's not used elsewhere in the driver. Switched to a regular base class with raise NotImplementedError — consistent with the existing codebase patterns.

In my comment I did not ask for the change. I asked for explanation. I don't know the differences between the two approaches, and wanted to understand them. This would allow us to choose better approach, but now I still don't know how they are different.

I think it would be better to stick to whatever is done here, it is going to be confusing if same problem solved in different ways.

dkropachev · 2026-02-16T14:58:39Z

Btw, why are you responding here, instead of responding to the comments as usual? It will be much harder to keep track of dicsussions.

Pardon, replied there, my bad.

github-code-quality bot found potential problems Jan 29, 2026

View reviewed changes

tests/unit/test_endpoints.py Fixed Show fixed Hide fixed

tests/unit/io/test_eventletreactor.py Fixed Show fixed Hide fixed

dkropachev force-pushed the dk/support-tls-tickets-fixes branch 2 times, most recently from cbbde06 to 5430bb7 Compare January 29, 2026 16:11

dkropachev changed the title ~~Dk/support tls tickets fixes~~ feat: add TLS session caching support Jan 29, 2026

dkropachev marked this pull request as ready for review January 29, 2026 17:16

dkropachev requested a review from Lorak-mmk January 29, 2026 17:16

dkropachev self-assigned this Jan 29, 2026

dkropachev mentioned this pull request Jan 29, 2026

Support TLS session resumption for TLS 1.2 and 1.3 with flexible caching strategies #633

Closed

7 tasks

dkropachev force-pushed the dk/support-tls-tickets-fixes branch from 5430bb7 to 6a84e73 Compare January 29, 2026 17:23

dkropachev added 12 commits February 3, 2026 19:12

test: add unit tests for endpoint tls_session_cache_key

796b891

Add tests verifying the tls_session_cache_key property for each endpoint type: - DefaultEndPoint returns (address, port) - SniEndPoint includes server_name to prevent cache collisions - UnixSocketEndPoint returns just the path

dkropachev force-pushed the dk/support-tls-tickets-fixes branch from 6a84e73 to b6ba877 Compare February 3, 2026 23:14

dkropachev requested a review from sylwiaszunejko February 3, 2026 23:14

sylwiaszunejko approved these changes Feb 9, 2026

View reviewed changes

Lorak-mmk requested changes Feb 16, 2026

View reviewed changes

dkropachev requested a review from Lorak-mmk February 16, 2026 14:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add TLS session caching support#657

feat: add TLS session caching support#657
dkropachev wants to merge 13 commits intomasterfrom
dk/support-tls-tickets-fixes

dkropachev commented Jan 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Lorak-mmk left a comment

Uh oh!

Uh oh!

Lorak-mmk Feb 16, 2026

Uh oh!

Lorak-mmk Feb 16, 2026

Uh oh!

dkropachev Feb 16, 2026

Uh oh!

Uh oh!

Uh oh!

dkropachev commented Feb 16, 2026

Uh oh!

Lorak-mmk commented Feb 16, 2026

Uh oh!

Lorak-mmk commented Feb 16, 2026

Uh oh!

dkropachev commented Feb 16, 2026

Uh oh!

dkropachev commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

dkropachev commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Testing

Documentation

Pre-review checklist

Uh oh!

Uh oh!

Uh oh!

Lorak-mmk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Lorak-mmk Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Lorak-mmk Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

dkropachev Feb 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dkropachev commented Feb 16, 2026

Uh oh!

Lorak-mmk commented Feb 16, 2026

Uh oh!

Lorak-mmk commented Feb 16, 2026

Uh oh!

dkropachev commented Feb 16, 2026

Uh oh!

dkropachev commented Feb 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dkropachev commented Jan 29, 2026 •

edited

Loading