SSL docs: Be more explicit about the threats of ignoring SSL errors

... because almost everybody gets it wrong almost every time.

(cherry picked from commit eaa18f306341818165c2ee4fc22750da04d5e45e)

Change-Id: I3ca1dfe9723d4d29339c2c0a1ebe421f5929c760
Reviewed-by: Richard J. Moore <rich@kde.org>

2 files changed, 14 insertions, 5 deletions

diff --git a/src/network/access/qnetworkreply.cpp b/src/network/access/qnetworkreply.cpp
index 77a8f65586..774d4edd6f 100644
--- a/src/network/access/qnetworkreply.cpp
+++ b/src/network/access/qnetworkreply.cpp
@@ -651,8 +651,13 @@ void QNetworkReply::ignoreSslErrors(const QList<QSslError> &errors)
     connection will be ignored, including certificate validation
     errors.
 
-    Note that calling this function without restraint may pose a
-    security risk for your application. Use it with care.
+    \warning Be sure to always let the user inspect the errors
+    reported by the sslErrors() signal, and only call this method
+    upon confirmation from the user that proceeding is ok.
+    If there are unexpected errors, the reply should be aborted.
+    Calling this method without inspecting the actual errors will
+    most likely pose a security risk for your application. Use it
+    with great care!
 
     This function can be called from the slot connected to the
     sslErrors() signal, which indicates which errors were
diff --git a/src/network/ssl/qsslsocket.cpp b/src/network/ssl/qsslsocket.cpp
index 668449ae6b..230e50f08b 100644
--- a/src/network/ssl/qsslsocket.cpp
+++ b/src/network/ssl/qsslsocket.cpp
@@ -1676,9 +1676,13 @@ void QSslSocket::startServerEncryption()
     will not emit the sslErrors() signal, and it is unnecessary to
     call this function.
 
-    Ignoring errors that occur during an SSL handshake should be done
-    with caution. A fundamental characteristic of secure connections
-    is that they should be established with an error free handshake.
+    \warning Be sure to always let the user inspect the errors
+    reported by the sslErrors() signal, and only call this method
+    upon confirmation from the user that proceeding is ok.
+    If there are unexpected errors, the connection should be aborted.
+    Calling this method without inspecting the actual errors will
+    most likely pose a security risk for your application. Use it
+    with great care!
 
     \sa sslErrors()
 */