docs: add citations for alert behavior (#4198)

aws · Sep 15, 2023 · e15bf7f · e15bf7f
1 parent e99e435
commit e15bf7f
Show file tree

Hide file tree

Showing 2 changed files with 23 additions and 3 deletions.
diff --git a/compliance/initialize_duvet.sh b/compliance/initialize_duvet.sh
@@ -1,5 +1,6 @@
 #/usr/bin/env bash
 
+duvet extract https://tools.ietf.org/rfc/rfc5246 # The Transport Layer Security (TLS) Protocol Version 1.2
 duvet extract https://tools.ietf.org/rfc/rfc5869 # HMAC-based Extract-and-Expand Key Derivation Function (HKDF)
 duvet extract https://tools.ietf.org/rfc/rfc8446 # The Transport Layer Security (TLS) Protocol Version 1.3
 duvet extract https://tools.ietf.org/rfc/rfc8448 # Example Handshake Traces for TLS 1.3

diff --git a/tls/s2n_alerts.c b/tls/s2n_alerts.c
@@ -143,6 +143,11 @@ static bool s2n_alerts_supported(struct s2n_connection *conn)
     return !s2n_connection_is_quic_enabled(conn);
 }
 
+/* In TLS1.3 all Alerts
+ *= https://tools.ietf.org/rfc/rfc8446#section-6
+ *# MUST be treated as error alerts when received
+ *# regardless of the AlertLevel in the message.
+ */
 static bool s2n_process_as_warning(struct s2n_connection *conn, uint8_t level, uint8_t type)
 {
     /* Only TLS1.2 considers the alert level. The alert level field is
@@ -222,7 +227,11 @@ int s2n_process_alert_fragment(struct s2n_connection *conn)
                 conn->config->cache_delete(conn, conn->config->cache_delete_data, conn->session_id, conn->session_id_len);
             }
 
-            /* All other alerts are treated as fatal errors */
+            /* All other alerts are treated as fatal errors.
+             *
+             *= https://tools.ietf.org/rfc/rfc8446#section-6
+             *# Unknown Alert types MUST be treated as error alerts.
+             */
             POSIX_GUARD_RESULT(s2n_connection_set_closed(conn));
             s2n_atomic_flag_set(&conn->error_alert_received);
             POSIX_BAIL(S2N_ERR_ALERT);
@@ -279,8 +288,18 @@ S2N_RESULT s2n_alerts_write_error_or_close_notify(struct s2n_connection *conn)
         return S2N_RESULT_OK;
     }
 
-    /* By default, s2n-tls sends a generic close_notify alert, even in
-     * response to fatal errors.
+    /*
+     *= https://tools.ietf.org/rfc/rfc8446#section-6.2
+     *= type=exception
+     *= reason=Specific alerts could expose a side-channel attack vector.
+     *# The phrases "terminate the connection with an X
+     *# alert" and "abort the handshake with an X alert" mean that the
+     *# implementation MUST send alert X if it sends any alert.
+     *
+     * By default, s2n-tls sends a generic close_notify alert, even in
+     * response to fatal errors. This is done to avoid potential
+     * side-channel attacks since specific alerts could reveal information
+     * about why the error occured.
      */
     uint8_t code = S2N_TLS_ALERT_CLOSE_NOTIFY;
     uint8_t level = S2N_TLS_ALERT_LEVEL_WARNING;