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

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

Change-Id: I54938ef094323ba8de02186b585b11b9579f3ca4
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 669725b016..fd3b7760cb 100644
--- a/src/network/access/qnetworkreply.cpp
+++ b/src/network/access/qnetworkreply.cpp
@@ -680,8 +680,13 @@ void QNetworkReply::ignoreSslErrorsImplementation(const QList<QSslError> &)
     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 cfc3c19bba..f0c3f40a28 100644
--- a/src/network/ssl/qsslsocket.cpp
+++ b/src/network/ssl/qsslsocket.cpp
@@ -1714,9 +1714,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()
 */