This is an automated email from the ASF dual-hosted git repository.
bneradt pushed a commit to branch 11-Dev
in repository https://gitbox.apache.org/repos/asf/trafficserver.git
The following commit(s) were added to refs/heads/11-Dev by this push:
new 9e0da423bb 11-Dev: Fix docs build (#12708)
9e0da423bb is described below
commit 9e0da423bb6ad03efedd90a95963b62187b08c09
Author: Brian Neradt <[email protected]>
AuthorDate: Mon Dec 1 11:01:21 2025 -0600
11-Dev: Fix docs build (#12708)
The 11-Dev branch has removed the TLS session caching feature, but did
not update the docs to remove references to it. This made the docs build
to fail. This updates the docs to remove session cache references.
---
doc/admin-guide/files/records.yaml.en.rst | 9 ++--
doc/admin-guide/performance/index.en.rst | 7 ---
.../tools/converting-records-to-yaml.en.rst | 7 ++-
.../api/functions/TSSslSession.en.rst | 51 +++++-------------
.../hooks-and-transactions/ssl-session-api.en.rst | 60 +++++-----------------
doc/release-notes/upgrading.en.rst | 1 -
doc/release-notes/whats-new.en.rst | 11 ----
7 files changed, 31 insertions(+), 115 deletions(-)
diff --git a/doc/admin-guide/files/records.yaml.en.rst
b/doc/admin-guide/files/records.yaml.en.rst
index 95510a9c36..b74195cd8f 100644
--- a/doc/admin-guide/files/records.yaml.en.rst
+++ b/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
diff --git a/doc/admin-guide/performance/index.en.rst
b/doc/admin-guide/performance/index.en.rst
index 461c6a9d84..33dccc4f39 100644
--- a/doc/admin-guide/performance/index.en.rst
+++ b/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
------------
diff --git a/doc/admin-guide/tools/converting-records-to-yaml.en.rst
b/doc/admin-guide/tools/converting-records-to-yaml.en.rst
index bb57ed2f03..dcc7af4cf1 100644
--- a/doc/admin-guide/tools/converting-records-to-yaml.en.rst
+++ b/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
---------
diff --git a/doc/developer-guide/api/functions/TSSslSession.en.rst
b/doc/developer-guide/api/functions/TSSslSession.en.rst
index 07a29d633e..2a2ed6290c 100644
--- a/doc/developer-guide/api/functions/TSSslSession.en.rst
+++ b/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.
diff --git
a/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst
b/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst
index f85ed86608..51641d7c88 100644
--- a/doc/developer-guide/plugins/hooks-and-transactions/ssl-session-api.en.rst
+++ b/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.
diff --git a/doc/release-notes/upgrading.en.rst
b/doc/release-notes/upgrading.en.rst
index 90df999654..6ad7a050a6 100644
--- a/doc/release-notes/upgrading.en.rst
+++ b/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
diff --git a/doc/release-notes/whats-new.en.rst
b/doc/release-notes/whats-new.en.rst
index f00111e551..af6233e2ed 100644
--- a/doc/release-notes/whats-new.en.rst
+++ b/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.
