doc: mention anti-replay mechanism for early datatmp-anti-replay

Signed-off-by: Daiki Ueno <dueno@redhat.com>

1 files changed, 82 insertions, 3 deletions

diff --git a/doc/cha-gtls-app.texi b/doc/cha-gtls-app.texi
index bf5b5bc847..e90934faf8 100644
--- a/doc/cha-gtls-app.texi
+++ b/doc/cha-gtls-app.texi
@@ -815,6 +815,7 @@ remaining until the next retransmission, or better the time until
 * Asynchronous operation::
 * Reducing round-trips::
 * Zero-roundtrip mode::
+* Anti-replay protection::
 * DTLS sessions::
 * DTLS and SCTP::
 @end menu
@@ -932,9 +933,13 @@ client should call this function before calling
 Note, however, that early data has weaker security properties than
 normal application data sent after handshake, such as lack of forward
 secrecy, no guarantees of non-replay between connections.  Thus it is
-disabled on the server side by default.  To enable it, set
-@acronym{GNUTLS_ENABLE_EARLY_DATA} on @funcref{gnutls_init}.  This
-option is only effective for server.
+disabled on the server side by default.  To enable it, the server
+needs to:
+@enumerate
+@item Set @acronym{GNUTLS_ENABLE_EARLY_DATA} on @funcref{gnutls_init}.  Note that this option only has effect on server.
+
+@item Enable anti-replay measure.  See @ref{Anti-replay protection} for the details.
+@end enumerate
 
 The server caches the received early data until it is read.  To set the
 maximum amount ot data to be stored in the cache, use
@@ -950,6 +955,80 @@ result with @acronym{GNUTLS_SFLAGS_EARLY_DATA}.  Similarly, on the
 server side, the same function and the same flag can be used to check
 whether it has actually accepted early data.
 
+The following example illustrates a typical usage of early data on the
+server side:
+@example
+#define MAX_EARLY_DATA_SIZE 16384
+
+static int
+handshake_hook_func(gnutls_session_t session, unsigned int htype,
+                    unsigned when, unsigned int incoming, const gnutls_datum_t *msg)
+@{
+    int ret;
+    char buf[MAX_EARLY_DATA_SIZE];
+
+    assert(htype == GNUTLS_HANDSHAKE_END_OF_EARLY_DATA);
+    assert(when == GNUTLS_HOOK_POST);
+
+    if (gnutls_session_get_flags(session) & GNUTLS_SFLAGS_EARLY_DATA) @{
+        ret = gnutls_record_recv_early_data(session, buf, sizeof(buf));
+        assert(ret >= 0);
+    @}
+
+    return ret;
+@}
+
+int main()
+@{
+  ...
+  /* Initialize anti-replay measure, which can be shared
+   * among multiple sessions.
+   */
+  gnutls_anti_replay_init(&anti_replay);
+
+  ...
+
+  gnutls_init(&server, GNUTLS_SERVER | GNUTLS_ENABLE_EARLY_DATA);
+  gnutls_record_set_max_early_data_size(server, MAX_EARLY_DATA_SIZE);
+  ...
+
+  /* Set the anti-replay measure to the session.
+   */
+  gnutls_anti_replay_enable(server, anti_replay);
+  ...
+
+  /* Retrieve early data in a handshake hook;
+   * you can also do that after handshake.
+   */
+  gnutls_handshake_set_hook_function(server, GNUTLS_HANDSHAKE_END_OF_EARLY_DATA,
+                                     GNUTLS_HOOK_POST, handshake_hook_func);
+  ...
+@}
+@end example
+
+
+@node Anti-replay protection
+@subsection Anti-replay protection
+
+When 0-RTT mode is used, it is suggested that the server should protect
+itself from replay attacks, where adversary reuses the same session
+ticket to establish a connection and sends crafted early data.
+
+GnuTLS provides a simple mechanism against replay attacks, following
+the method called ClientHello recording.  When session ticket is
+accepted, the server derives an unique value from the ClientHello
+message and checks if it is already seen.  If there is any duplicate,
+the server rejects early data.
+
+The mechanism shall be globally initialized with
+@funcref{gnutls_anti_replay_init}, and then attached to a session
+using @funcref{gnutls_anti_replay_enable}.  It can be deinitialized
+with @funcref{gnutls_anti_replay_deinit}.
+
+By default, the mechanism uses an on-memory database.  For a
+long-running server or distributed servers, you can set the custom
+backend functions with @funcref{gnutls_anti_replay_set_functions}.
+
 
 @node DTLS sessions
 @subsection DTLS sessions