Update documentation.

Change-Id: I8fca0df0ea66adba0898d95f8249ea1b7f33892a
Reviewed-by: Kurt Pattyn <pattyn.kurt@gmail.com>

diff --git a/src/websockets/qdefaultmaskgenerator_p.cpp b/src/websockets/qdefaultmaskgenerator_p.cpp
index 814e04d..da166ac 100644 (file)
--- a/src/websockets/qdefaultmaskgenerator_p.cpp
+++ b/src/websockets/qdefaultmaskgenerator_p.cpp
@@ -38,6 +38,26 @@
 ** $QT_END_LICENSE$
 **
 ****************************************************************************/
 ** $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>
 
 #include "qdefaultmaskgenerator_p.h"
 #include <QDateTime>


@@ -45,21 +65,42 @@
 
 QT_BEGIN_NAMESPACE
 
 
 QT_BEGIN_NAMESPACE
 

+/*!
+    Constructs a new QDefaultMaskGenerator with the given \a parent.
+
+    \internal
+*/

 QDefaultMaskGenerator::QDefaultMaskGenerator(QObject *parent) :
     QMaskGenerator(parent)
 {
 }
 
 QDefaultMaskGenerator::QDefaultMaskGenerator(QObject *parent) :
     QMaskGenerator(parent)
 {
 }
 

+/*!
+    Destroys the QDefaultMaskGenerator object.
+
+    \internal
+*/

 QDefaultMaskGenerator::~QDefaultMaskGenerator()
 {
 }
 
 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;
 }
 
 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());
 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 (file)
--- a/src/websockets/qmaskgenerator.cpp
+++ b/src/websockets/qmaskgenerator.cpp
@@ -41,6 +41,7 @@
 
 /*!
     \class QMaskGenerator
 
 /*!
     \class QMaskGenerator

+

     \inmodule QtWebSockets
 
     \brief The QMaskGenerator class provides an abstract base for custom 32-bit mask generators.
     \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 (file)
--- 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>
 #include "qsslserver_p.h"
 
 #include <QtNetwork/QSslSocket>


@@ -46,26 +56,57 @@
 
 QT_BEGIN_NAMESPACE
 
 
 QT_BEGIN_NAMESPACE
 

+/*!
+    Constructs a new QSslServer with the given \a parent.
+
+    \internal
+*/

 QSslServer::QSslServer(QObject *parent) :
     QTcpServer(parent),
     m_sslConfiguration(QSslConfiguration::defaultConfiguration())
 {
 }
 
 QSslServer::QSslServer(QObject *parent) :
     QTcpServer(parent),
     m_sslConfiguration(QSslConfiguration::defaultConfiguration())
 {
 }
 

+/*!
+    Destroys the QSslServer.
+
+    All open connections are closed.
+
+    \internal
+*/

 QSslServer::~QSslServer()
 {
 }
 
 QSslServer::~QSslServer()
 {
 }
 

+/*!
+    Sets the \a sslConfiguration to use.
+
+    \sa QSslSocket::setSslConfiguration()
+
+    \internal
+*/

 void QSslServer::setSslConfiguration(const QSslConfiguration &sslConfiguration)
 {
     m_sslConfiguration = sslConfiguration;
 }
 
 void QSslServer::setSslConfiguration(const QSslConfiguration &sslConfiguration)
 {
     m_sslConfiguration = sslConfiguration;
 }
 

+/*!
+    Returns the current ssl configuration.
+
+    \internal
+*/

 QSslConfiguration QSslServer::sslConfiguration() const
 {
     return m_sslConfiguration;
 }
 
 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();
 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 (file)
--- 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}.
 
     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,
     \warning To generate masks, this implementation of WebSockets uses the cryptographically
     insecure qrand() function.
     For more information about the importance of good masking,