update documentation on GNUTLS_AUTO_REAUTH and gnutls_record_get_direction [ci skip]

That clarifiesthe intention, and adds warning of using this flag when
multiple threads are involved. Based on suggestion by Michael Catanzaro.

Relates: #615

Signed-off-by: Nikos Mavrogiannopoulos <nmav@gnutls.org>

diff --git a/lib/includes/gnutls/gnutls.h.in b/lib/includes/gnutls/gnutls.h.in
index 789e3743154c301012d56f31cb2c0dc6f1d017fd..73141a3a3b7c7e66f2b10e76a0492d1083c20283 100644 (file)
--- a/lib/includes/gnutls/gnutls.h.in
+++ b/lib/includes/gnutls/gnutls.h.in
@@ -425,9 +425,11 @@ typedef enum {
  * @GNUTLS_AUTO_REAUTH: Enable transparent re-authentication in client side when the server
  *    requests to. That is, reauthentication is handled within gnutls_record_recv(), and
  *    the %GNUTLS_E_REHANDSHAKE or %GNUTLS_E_REAUTH_REQUEST are not returned. This must be
- *    enabled with %GNUTLS_POST_HANDSHAKE_AUTH for TLS1.3, and it requires to restore interrupted
- *    calls to gnutls_record_recv() based on the output of gnutls_record_get_direction(), i.e.,
- *    gnutls_record_recv() could also be interrupted when sending when this flag is enabled.
+ *    enabled with %GNUTLS_POST_HANDSHAKE_AUTH for TLS1.3. Enabling this flag requires to restore
+ *    interrupted calls to gnutls_record_recv() based on the output of gnutls_record_get_direction(),
+ *    since gnutls_record_recv() could be interrupted when sending when this flag is enabled.
+ *    Note this flag may not be used if you are using the same session for sending and receiving
+ *    in different threads.
  *
  * Enumeration of different flags for gnutls_init() function. All the flags
  * can be combined except @GNUTLS_SERVER and @GNUTLS_CLIENT which are mutually

diff --git a/lib/state.c b/lib/state.c
index 01288ad474520781e3c3757f7b0659a294555280..5364d5e727c92bca4f840f01a307a0b110b74e07 100644 (file)
--- a/lib/state.c
+++ b/lib/state.c
@@ -1052,12 +1052,15 @@ void
  * gnutls_record_get_direction:
  * @session: is a #gnutls_session_t type.
  *
- * This function provides information about the internals of the
- * record protocol and is only useful if a prior gnutls function call,
- * e.g.  gnutls_handshake(), was interrupted for some reason. That
- * is, if a function returned %GNUTLS_E_INTERRUPTED or
- * %GNUTLS_E_AGAIN. In such a case, you might want to call select()
- * or poll() before restoring the interrupted gnutls function.
+ * This function is useful to determine whether a GnuTLS function was interrupted
+ * while sending or receiving, so that select() or poll() may be called appropriately.
+ *
+ * It provides information about the internals of the record
+ * protocol and is only useful if a prior gnutls function call,
+ * e.g.  gnutls_handshake(), was interrupted and returned
+ * %GNUTLS_E_INTERRUPTED or %GNUTLS_E_AGAIN. After such an interrupt
+ * applications may call select() or poll() before restoring the
+ * interrupted GnuTLS function.
  *
  * This function's output is unreliable if you are using the same
  * @session in different threads, for sending and receiving.