Update doc of ssl_set_authmode()
diff --git a/include/polarssl/ssl.h b/include/polarssl/ssl.h
index 1e52229..dd3521d 100644
--- a/include/polarssl/ssl.h
+++ b/include/polarssl/ssl.h
@@ -620,6 +620,12 @@
*
* SSL_VERIFY_REQUIRED: peer *must* present a valid certificate,
* handshake is aborted if verification failed.
+ *
+ * \note On client, SSL_VERIFY_REQUIRED is the recommended mode.
+ * With SSL_VERIFY_OPTIONAL, the user needs to call ssl_get_verify_result() at
+ * the right time(s), which may not be obvious, while REQUIRED always perform
+ * the verification as soon as possible. For example, REQUIRED was protecting
+ * against the "triple handshake" attack even before it was found.
*/
void ssl_set_authmode( ssl_context *ssl, int authmode );