11-Dev: Fix docs build

doc/admin-guide/files/records.yaml.en.rst

@@ -4049,14 +4049,11 @@ SSL Termination
 
 .. ts:cv:: CONFIG proxy.config.ssl.server.session_ticket.number INT 2
 
-  This configuration control the number of TLSv1.3 session tickets that are issued.
-  Take into account that setting the value to 0 will disable session caching for TLSv1.3
+  This configuration controls the number of TLSv1.3 session tickets that are issued.
+  Setting the value to 0 will disable session ticket-based session resumption for TLSv1.3
   connections.
 
-  Lowering this setting to ``1`` can be interesting when ``proxy.config.ssl.session_cache.mode`` is enabled because
-  otherwise for every new TLSv1.3 connection two session IDs will be inserted in the session cache.
-  On the other hand, if ``proxy.config.ssl.session_cache.mode``  is disabled, using the default value is recommended.
-  In those scenarios, increasing the number of tickets could be potentially beneficial for clients performing
+  Increasing the number of tickets could be potentially beneficial for clients performing
   multiple requests over concurrent TLS connections as per RFC 8446 clients SHOULDN'T reuse TLS Tickets.
 
   For more information see https://www.openssl.org/docs/man1.1.1/man3/SSL_CTX_set_num_tickets.html

doc/admin-guide/performance/index.en.rst

@@ -405,9 +405,6 @@ will persist, specified in seconds using
 the remote OCSP responders, in seconds, with
 :ts:cv:`proxy.config.ssl.ocsp.request_timeout`.
 
-Lastly, you can control the number of seconds for which SSL sessions will be
-cached in |TS| using :ts:cv:`proxy.config.ssl.session_cache.timeout`.
-
 .. code-block:: yaml
 
    records:
@@ -416,8 +413,6 @@ cached in |TS| using :ts:cv:`proxy.config.ssl.session_cache.timeout`.
        ocsp:
          cache_timeout: 3600
          request_timeout: 10
-       session_cache:
-         timeout: 0
 
 
 Transaction Activity Timeouts
@@ -528,8 +523,6 @@ SSL-Specific Options
 ~~~~~~~~~~~~~~~~~~~~
 
 :ts:cv:`proxy.config.ssl.max_record_size`
-:ts:cv:`proxy.config.ssl.session_cache.mode`
-:ts:cv:`proxy.config.ssl.session_cache.size`
 
 Thread Types
 ------------

doc/admin-guide/tools/converting-records-to-yaml.en.rst

@@ -150,21 +150,20 @@ Converting a file with a detailed output.
    $ python3 convert2yaml.py -f records.config -o records.yaml
    [████████████████████████████████████████] 494/494
 
-   ┌■ 8 Renamed records:
+   ┌■ 7 Renamed records:
    └┬──» #1 : proxy.config.output.logfile -> proxy.config.output.logfile.name
     ├──» #2 : proxy.config.exec_thread.autoconfig -> proxy.config.exec_thread.autoconfig.enabled
     ├──» #3 : proxy.config.hostdb -> proxy.config.hostdb.enabled
     ├──» #4 : proxy.config.tunnel.prewarm -> proxy.config.tunnel.prewarm.enabled
     ├──» #5 : proxy.config.ssl.TLSv1_3 -> proxy.config.ssl.TLSv1_3.enabled
     ├──» #6 : proxy.config.ssl.client.TLSv1_3 -> proxy.config.ssl.client.TLSv1_3.enabled
-    ├──» #7 : proxy.config.ssl.origin_session_cache -> proxy.config.ssl.origin_session_cache.enabled
-    └──» #8 : proxy.config.ssl.session_cache -> proxy.config.ssl.session_cache.mode
+    └──» #7 : proxy.config.ssl.origin_session_cache -> proxy.config.ssl.origin_session_cache.enabled
 
 
 There are a few things to note here:
 
 Line 2. A total of ``494`` from ``494`` records were converted.
-Line 4. A total of ``8`` records were renamed.
+Line 4. A total of ``7`` records were renamed.
 
 Example 2
 ---------

doc/developer-guide/api/functions/TSSslSession.en.rst

@@ -18,8 +18,8 @@
 .. include:: ../../../common.defs
 .. default-domain:: cpp
 
-TSSslSession
-************
+TSSslTicketKeyUpdate
+********************
 
 Synopsis
 ========
@@ -28,47 +28,20 @@ Synopsis
 
     #include <ts/ts.h>
 
-.. function:: TSSslSession TSSslSessionGet(const TSSslSessionID * sessionid)
-.. function:: int TSSslSessionGetBuffer(const TSSslSessionID * sessionid, char * buffer, int * len_ptr)
-.. function:: TSReturnCode TSSslSessionInsert(const TSSslSessionID * sessionid, TSSslSession addSession, TSSslConnection ssl_conn)
-.. function:: TSReturnCode TSSslSessionRemove(const TSSslSessionID * sessionid)
-.. function:: void TSSslTicketKeyUpdate(char * ticketData, int ticketDataLength)
+.. function:: TSReturnCode TSSslTicketKeyUpdate(char * ticketData, int ticketDataLength)
 
 Description
 ===========
 
-These functions work with the internal ATS session cache.  These functions are only useful if the ATS internal
-session cache is enabled by setting :ts:cv:`proxy.config.ssl.session_cache.mode` has been set to 2.
+.. note::
 
-These functions tend to be used with the :enumerator:`TS_SSL_SESSION_HOOK`.
+   The session ID-based session cache and its associated APIs (``TSSslSessionGet``, ``TSSslSessionGetBuffer``,
+   ``TSSslSessionInsert``, ``TSSslSessionRemove``) were removed in ATS 11.x.
+   TLS session resumption is now only supported via session tickets.
 
-The functions work with the :type:`TSSslSessionID` object to identify sessions to retrieve, insert, or delete.
+:func:`TSSslTicketKeyUpdate` updates the running ATS process to use a new set of Session Ticket Encryption keys.
+This behaves the same way as updating the session ticket encrypt key file with new data and reloading the
+current ATS process. However, this API does not require writing session ticket encryption keys to disk.
 
-The functions also work with the :type:`TSSslSession` object which can be cast to a pointer to the OpenSSL SSL_SESSION object.
-
-These functions perform the appropriate locking on the session cache to avoid errors.
-
-The :func:`TSSslSessionGet` and :func:`TSSslSessionGetBuffer` functions retrieve the :type:`TSSslSession` object that is identified by the
-:type:`TSSslSessionID` object.  If there is no matching session object, :func:`TSSslSessionGet` returns nullptr and :func:`TSSslSessionGetBuffer`
-returns 0.
-
-:func:`TSSslSessionGetBuffer` returns the session information serialized in a buffer that can be shared between processes.
-When the function is called len_ptr should point to the amount of space
-available in the buffer parameter.  The function returns the amount of data really needed to encode the session.  len_ptr is
-updated with the amount of data actually stored in the buffer.
-:func:`TSSslSessionGetBuffer` will not overrun the provided buffer, but the caller should ensure that the data's size was not larger
-than the buffer by comparing the returned value with the value of len_ptr. If the returned value is larger than the buffer size,
-then the session data did not fit in the buffer and the session data stored in the buffer output variable should not be used.
-
-
-:func:`TSSslSessionInsert` inserts the session specified by the addSession parameter into the ATS session cache under the sessionid key.
-If there is already an entry in the cache for the session id key, it is first removed before the new entry is added.
-
-:func:`TSSslSessionRemove` removes the session entry from the session cache that is keyed by sessionid.
-
-:func:`TSSslTicketKeyUpdate` updates the running ATS process to use a new set of Session Ticket Encryption keys.  This behaves the same way as
-updating the session ticket encrypt key file with new data and reloading the current ATS process.  However, this API does not
-require writing session ticket encryption keys to disk.
-
-If both the ticket key files and :func:`TSSslTicketKeyUpdate` are used to update session ticket encryption keys, ATS will use the
-most recent update regardless if whether it was made by file and configuration reload or API.
+If both the ticket key files and :func:`TSSslTicketKeyUpdate` are used to update session ticket encryption keys,
+ATS will use the most recent update regardless of whether it was made by file and configuration reload or API.

doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst

@@ -21,62 +21,28 @@
 
 .. default-domain:: cpp
 
-TLS Session Plugin API
-**********************
+TLS Session Ticket Key Plugin API
+**********************************
 
-These interfaces enable a plugin to hook into operations on the ATS TLS session cache.  ATS also provides API's
-to enable the plugin to update the session cache based on outside information, e.g. peer servers.
+This interface enables a plugin to update the session ticket encryption keys used for TLS session resumption.
 
-.. enumerator:: TS_SSL_SESSION_HOOK
+.. note::
 
-This hook is invoked when a change has been made to the ATS session cache or a session has been accessed
-from ATS via OpenSSL.  These hooks are only activated if the ATS implementation of the session cache is in
-use.  This means :ts:cv:`proxy.config.ssl.session_cache.mode` has been set to 2.
-
-The hook callback has the following signature
-
-.. function:: int SSL_session_callback(TSCont contp, TSEvent event, void * edata)
-
-The edata parameter is a pointer to a :type:`TSSslSessionID`.
-
-This callback in synchronous since the underlying OpenSSL callback is unable to pause processing.
-
-The following events can be sent to this callback
-
-.. c:enumerator:: TS_EVENT_SSL_SESSION_NEW
-
-   Sent after a new session has been inserted into the SSL session cache.  The plugin can call :func:`TSSslSessionGet` to retrieve the actual session object.  The plugin could communicate information about the new session to other processes or update additional logging or statistics.
-
-.. c:enumerator:: TS_EVENT_SSL_SESSION_GET
-
-   Sent after a session has been fetched from the SSL session cache by a client request.  The plugin could update additional logging and statistics.
-
-.. c:enumerator:: TS_EVENT_SSL_SESSION_REMOVE
-
-   Sent after a session has been removed from the SSL session cache.  The plugin could communication information about the session removal to other processes or update additional logging and statistics.
+   The session ID-based session cache and its associated APIs (``TSSslSessionGet``, ``TSSslSessionGetBuffer``,
+   ``TSSslSessionInsert``, ``TSSslSessionRemove``, and ``TS_SSL_SESSION_HOOK``) were removed in ATS 11.x.
+   TLS session resumption is now only supported via session tickets.
 
 Utility Functions
-******************
+*****************
 
-A number of API functions will likely be used with this hook.
-
-* :func:`TSSslSessionGet`
-* :func:`TSSslSessionGetBuffer`
-* :func:`TSSslSessionInsert`
-* :func:`TSSslSessionRemove`
 * :func:`TSSslTicketKeyUpdate`
 
 Example Use Case
 ****************
 
-Consider deploying a set of ATS servers as a farm behind a layer 4 load balancer.  The load balancer does not
-guarantee that all the requests from a single client are directed to the same ATS box.  Therefore, to maximize TLS session
-reuse, the servers should share session state via some external communication library like redis or rabbitmq.
-
-To do this, they write a plugin that sets the :enumerator:`TS_SSL_SESSION_HOOK`.  When the hook is triggered, the plugin function sends the
-updated session state to the other ATS servers via the communication library.
-
-The plugin also has thread that listens for updates and calls :func:`TSSslSessionInsert` and :func:`TSSslSessionRemove` to update the local session cache accordingly.
+Consider deploying a set of ATS servers as a farm behind a layer 4 load balancer. To enable TLS session
+ticket-based resumption across all servers, they need to share the same session ticket encryption keys.
 
-The plugin can also engage in a protocol to periodically update the session ticket encryption key and communicate the new key to its
-peers.  The plugin calls :func:`TSSslTicketKeyUpdate` to update the local ATS process with the newest keys and the last N keys.
+A plugin can engage in a protocol to periodically update the session ticket encryption key and communicate
+the new key to its peers. The plugin calls :func:`TSSslTicketKeyUpdate` to update the local ATS process
+with the newest keys and the last N keys.

doc/release-notes/upgrading.en.rst

@@ -172,7 +172,6 @@ The following :file:`records.yaml` changes have been made:
 - The records.yaml entry ``proxy.config.exec_thread.autoconfig`` has been renamed to :ts:cv:`proxy.config.exec_thread.autoconfig.enabled`.
 - The records.yaml entry ``proxy.config.tunnel.prewarm`` has been renamed to :ts:cv:`proxy.config.tunnel.prewarm.enabled`.
 - The records.yaml entry ``proxy.config.ssl.origin_session_cache`` has been renamed to :ts:cv:`proxy.config.ssl.origin_session_cache.enabled`.
-- The records.yaml entry ``proxy.config.ssl.session_cache`` has been renamed to :ts:cv:`proxy.config.ssl.session_cache.mode`.
 - The records.yaml entry ``proxy.config.ssl.TLSv1_3`` has been renamed to :ts:cv:`proxy.config.ssl.TLSv1_3.enabled`.
 - The records.yaml entry ``proxy.config.ssl.client.TLSv1_3`` has been renamed to :ts:cv:`proxy.config.ssl.client.TLSv1_3.enabled`.
 - The records.yaml entry :ts:cv:`proxy.config.allocator.iobuf_chunk_sizes` has been added

doc/release-notes/whats-new.en.rst

@@ -108,17 +108,6 @@ Configuration
 
 * Added :ts:cv:`proxy.config.http.negative_revalidating_list` to configure the
   list of status codes that apply to the negative revalidating feature
-* Added :ts:cv:`proxy.config.ssl.session_cache.mode` to control TLS session caching.
-  This is intended to replace the legacy :ts:cv:`proxy.config.ssl.session_cache.enabled` and
-  ``proxy.config.ssl.session_cache.value`` configurations. The
-  :ts:cv:`proxy.config.ssl.session_cache.enabled` setting was documented but
-  never implemented, while ``proxy.config.ssl.session_cache.value`` was
-  implemented but not documented. The new :ts:cv:`proxy.config.ssl.session_cache.mode`
-  functions just like the legacy ``proxy.config.ssl.session_cache.value`` did
-  in the ealier 10.0 release. The :ts:cv:`proxy.config.ssl.session_cache.mode`
-  setting provides a clear and consistent interface going forward.  For backward
-  compatibility, ``.enabled`` is now implemented, but both ``.enabled`` and
-  ``.value`` will be removed in ATS 11.x.