Merge branch 'ajuaristi-update-docs' into 'master'

Update docs for session ticket key rotation

Closes #581

See merge request gnutls/gnutls!768

1 files changed, 15 insertions, 4 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index 1575c8fa52..64c662ce00 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -1714,16 +1714,27 @@ for expiration.
 A server supporting session tickets must generate ticket encryption
 and authentication keys using @funcref{gnutls_session_ticket_key_generate}.
 Those keys should be associated with the GnuTLS session using
-@funcref{gnutls_session_ticket_enable_server}, and should be rotated regularly
-(e.g., every few hours), to prevent them from becoming long-term keys which
-if revealed could be used to decrypt all previous sessions.
+@funcref{gnutls_session_ticket_enable_server}.
+
+Those will be the initial keys, but GnuTLS will rotate them regularly. The key rotation interval
+can be changed with @funcref{gnutls_db_set_cache_expiration} and will be set to
+three times the ticket expiration time (ie. three times the value given in that function).
+Every such interval, new keys will be generated from those initial keys. This is a necessary mechanism
+to prevent the keys from becoming long-term keys
+and as such preserve forward-secrecy in the issued session tickets. If no explicit key rotation interval
+is provided, GnuTLS will rotate them every 18 hours by default.
+
+The master key can be shared between processes or between systems. Processes which share the same master key
+will generate the same rotated subkeys, assuming they share the same time (irrespective of timezone differences).
 
 @showfuncdesc{gnutls_session_ticket_enable_server}
 @showfuncdesc{gnutls_session_ticket_key_generate}
 @showfuncdesc{gnutls_session_resumption_requested}
 
 The expiration time for session resumption, either in tickets or stored data
-is set using @funcref{gnutls_db_set_cache_expiration}.
+is set using @funcref{gnutls_db_set_cache_expiration}. This function also controls
+the ticket key rotation period. Currently, the session key rotation interval is set
+to 3 times the expiration time set by this function.
 
 Under TLS 1.3, the server can send a new session ticket at any time
 using @funcref{gnutls_session_ticket_send}.