docs: update blinding docs (#4686)

docs/usage-guide/topics/ch03-error-handling.md

@@ -61,13 +61,17 @@ if (s2n_negotiate(conn, &blocked) < 0) {
 }
 ```
 
-### Blinding
+## Blinding
 
-Blinding is a mitigation against timing side-channels which in some cases can leak information about encrypted data. By default s2n-tls will cause a thread to sleep between 10 and 30 seconds whenever tampering is detected.
+Blinding is a mitigation against timing side-channels which in some cases can leak information about encrypted data. [This](https://aws.amazon.com/blogs/security/s2n-and-lucky-13/) blog post includes a good description of blinding and how it mitigates timing side-channels like Lucky13.
 
-Setting the `S2N_SELF_SERVICE_BLINDING` option with `s2n_connection_set_blinding()` turns off this behavior. This is useful for applications that are handling many connections in a single thread. In that case, if `s2n_recv()` or `s2n_negotiate()` return an error, self-service applications must call `s2n_connection_get_delay()` and pause activity on the connection for the specified number of nanoseconds before calling `close()` or `shutdown()`. `s2n_shutdown()` will fail if called before the blinding delay elapses.
+By default s2n-tls will cause a thread to sleep between 10 and 30 seconds whenever an error triggered by the peer occurs. The default implementation of blinding blocks the thread.
 
-### Stacktraces
+For non-blocking blinding, an application can handle the delay itself. This is useful for applications that are handling many connections in a single thread. The application should set the `S2N_SELF_SERVICE_BLINDING` option with `s2n_connection_set_blinding()`. After `s2n_recv()` or `s2n_negotiate()` return an error, the application must call `s2n_connection_get_delay()` and pause activity on the connection for the specified number of nanoseconds before calling `s2n_shutdown()`, `close()`, or `shutdown()`. `s2n_shutdown()` will fail if called before the blinding delay elapses. To correctly implement self-service blinding, the application must have nanosecond-level resolution on its implementation of the delay. Not properly implementing self-service blinding (such as by not waiting for the full delay before calling `close()` on the underlying socket) makes an application potentially vulnerable to timing side-channel attacks.
+
+The maximum blinding delay is configurable via `s2n_config_set_max_blinding_delay()`. However, setting a maximum delay lower than the recommended default (30s) will make timing side-channel attacks easier. The lower the delay, the fewer requests and less total time an attacker will need to execute a side-channel attack. If a lower delay is required for reasons such as client timeouts, then the highest value practically possible should be chosen to limit risk. Do not lower the blinding delay without fully understanding the risks.
+
+## Stacktraces
 s2n-tls has an mechanism to capture stacktraces when errors occur.
 This mechanism is off by default, but can be enabled in code by calling `s2n_stack_traces_enabled_set()`.
 It can be enabled globally by setting the environment variable `S2N_PRINT_STACKTRACE=1`.

docs/usage-guide/topics/ch07-io.md

@@ -51,6 +51,8 @@ if (flags < 0) return S2N_FAILURE;
 if (fcntl(fd, F_SETFL, flags | O_NONBLOCK) < 0) return S2N_FAILURE;
 ```
 
+Note: If an application requires non-blocking IO, it likely also requires self-service blinding. See [Blinding](./ch03-error-handling.md#Blinding).
+
 ## Errors and Alerts
 
 If the peer sends an alert, the next call to a read IO method will report **S2N_FAILURE** and