From 8cda01eb77b9f52ad8f5d58e65d7cd76d8e20154 Mon Sep 17 00:00:00 2001
From: Kurt Pattyn <pattyn.kurt@gmail.com>
Date: Sun, 9 Mar 2014 13:11:58 +0100
Subject: [PATCH] Update documentation.

Change-Id: I8fca0df0ea66adba0898d95f8249ea1b7f33892a
Reviewed-by: Kurt Pattyn <pattyn.kurt@gmail.com>
---
 src/websockets/qdefaultmaskgenerator_p.cpp | 41 ++++++++++++++++++++++++++++++
 src/websockets/qmaskgenerator.cpp          |  1 +
 src/websockets/qsslserver.cpp              | 41 ++++++++++++++++++++++++++++++
 src/websockets/qwebsocket.cpp              |  4 +++
 4 files changed, 87 insertions(+)

diff --git a/src/websockets/qdefaultmaskgenerator_p.cpp b/src/websockets/qdefaultmaskgenerator_p.cpp
index 814e04d..da166ac 100644
--- a/src/websockets/qdefaultmaskgenerator_p.cpp
+++ b/src/websockets/qdefaultmaskgenerator_p.cpp
@@ -38,6 +38,26 @@
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/
+/*!
+    \class QDefaultMaskGenerator
+
+    \inmodule QtWebSockets
+
+    \brief The QDefaultMaskGenerator class provides the default mask generator for QtWebSockets.
+
+    The WebSockets specification as outlined in {http://tools.ietf.org/html/rfc6455}{RFC 6455}
+    requires that all communication from client to server must be masked. This is to prevent
+    malicious scripts to attack bad behaving proxies.
+    For more information about the importance of good masking,
+    see \l {http://w2spconf.com/2011/papers/websocket.pdf}.
+    The default mask generator uses the cryptographically insecure qrand() function.
+    The best measure against attacks mentioned in the document above,
+    is to use QWebSocket over a secure connection (\e wss://).
+    In general, always be careful to not have 3rd party script access to
+    a QWebSocket in your application.
+
+    \internal
+*/
 
 #include "qdefaultmaskgenerator_p.h"
 #include <QDateTime>
@@ -45,21 +65,42 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    Constructs a new QDefaultMaskGenerator with the given \a parent.
+
+    \internal
+*/
 QDefaultMaskGenerator::QDefaultMaskGenerator(QObject *parent) :
     QMaskGenerator(parent)
 {
 }
 
+/*!
+    Destroys the QDefaultMaskGenerator object.
+
+    \internal
+*/
 QDefaultMaskGenerator::~QDefaultMaskGenerator()
 {
 }
 
+/*!
+    Seeds the QDefaultMaskGenerator using qsrand().
+    When seed() is not called, no seed is used at all.
+
+    \internal
+*/
 bool QDefaultMaskGenerator::seed()
 {
     qsrand(static_cast<uint>(QDateTime::currentMSecsSinceEpoch()));
     return true;
 }
 
+/*!
+    Generates a new random mask using the insecure qrand() method.
+
+    \internal
+*/
 quint32 QDefaultMaskGenerator::nextMask()
 {
     return quint32((double(qrand()) / RAND_MAX) * std::numeric_limits<quint32>::max());
diff --git a/src/websockets/qmaskgenerator.cpp b/src/websockets/qmaskgenerator.cpp
index 3e4ce17..04f5e1e 100644
--- a/src/websockets/qmaskgenerator.cpp
+++ b/src/websockets/qmaskgenerator.cpp
@@ -41,6 +41,7 @@
 
 /*!
     \class QMaskGenerator
+
     \inmodule QtWebSockets
 
     \brief The QMaskGenerator class provides an abstract base for custom 32-bit mask generators.
diff --git a/src/websockets/qsslserver.cpp b/src/websockets/qsslserver.cpp
index d1add19..e5faded 100644
--- a/src/websockets/qsslserver.cpp
+++ b/src/websockets/qsslserver.cpp
@@ -39,6 +39,16 @@
 **
 ****************************************************************************/
 
+/*!
+    \class QSslServer
+
+    \inmodule QtWebSockets
+
+    \brief Implements a secure TCP server over SSL.
+
+    \internal
+*/
+
 #include "qsslserver_p.h"
 
 #include <QtNetwork/QSslSocket>
@@ -46,26 +56,57 @@
 
 QT_BEGIN_NAMESPACE
 
+/*!
+    Constructs a new QSslServer with the given \a parent.
+
+    \internal
+*/
 QSslServer::QSslServer(QObject *parent) :
     QTcpServer(parent),
     m_sslConfiguration(QSslConfiguration::defaultConfiguration())
 {
 }
 
+/*!
+    Destroys the QSslServer.
+
+    All open connections are closed.
+
+    \internal
+*/
 QSslServer::~QSslServer()
 {
 }
 
+/*!
+    Sets the \a sslConfiguration to use.
+
+    \sa QSslSocket::setSslConfiguration()
+
+    \internal
+*/
 void QSslServer::setSslConfiguration(const QSslConfiguration &sslConfiguration)
 {
     m_sslConfiguration = sslConfiguration;
 }
 
+/*!
+    Returns the current ssl configuration.
+
+    \internal
+*/
 QSslConfiguration QSslServer::sslConfiguration() const
 {
     return m_sslConfiguration;
 }
 
+/*!
+    Called when a new connection is established.
+
+    Converts \a socket to a QSslSocket.
+
+    \internal
+*/
 void QSslServer::incomingConnection(qintptr socket)
 {
     QSslSocket *pSslSocket = new QSslSocket();
diff --git a/src/websockets/qwebsocket.cpp b/src/websockets/qwebsocket.cpp
index 707d459..85b45c0 100644
--- a/src/websockets/qwebsocket.cpp
+++ b/src/websockets/qwebsocket.cpp
@@ -60,6 +60,10 @@
     QWebSocket only supports version 13 of the WebSocket protocol, as outlined in
     \l {http://tools.ietf.org/html/rfc6455}{RFC 6455}.
 
+    \note Some proxies do not understand certain HTTP headers used during a web socket handshake.
+    In that case, non-secure web socket connections fail. The best way to mitigate against
+    this problem is to use web sockets over a secure connection.
+
     \warning To generate masks, this implementation of WebSockets uses the cryptographically
     insecure qrand() function.
     For more information about the importance of good masking,
-- 
2.7.4