1 /****************************************************************************

     2 **

     3 ** Copyright (C) 2010 Nokia Corporation and/or its subsidiary(-ies).

     4 ** All rights reserved.

     5 ** Contact: Nokia Corporation (qt-info@nokia.com)

     6 **

     7 ** This file is part of the QtNetwork module of the Qt Toolkit.

     8 **

     9 ** $QT_BEGIN_LICENSE:LGPL$

    10 ** No Commercial Usage

    11 ** This file contains pre-release code and may not be distributed.

    12 ** You may use this file in accordance with the terms and conditions

    13 ** contained in the Technology Preview License Agreement accompanying

    14 ** this package.

    15 **

    16 ** GNU Lesser General Public License Usage

    17 ** Alternatively, this file may be used under the terms of the GNU Lesser

    18 ** General Public License version 2.1 as published by the Free Software

    19 ** Foundation and appearing in the file LICENSE.LGPL included in the

    20 ** packaging of this file.  Please review the following information to

    21 ** ensure the GNU Lesser General Public License version 2.1 requirements

    22 ** will be met: http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.

    23 **

    24 ** In addition, as a special exception, Nokia gives you certain additional

    25 ** rights.  These rights are described in the Nokia Qt LGPL Exception

    26 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.

    27 **

    28 ** If you have questions regarding the use of this file, please contact

    29 ** Nokia at qt-info@nokia.com.

    30 **

    31 **

    32 **

    33 **

    34 **

    35 **

    36 **

    37 **

    38 ** $QT_END_LICENSE$

    39 **

    40 ****************************************************************************/

    41 

    42 

    43 //#define QSSLSOCKET_DEBUG

    44 

    45 /*!

    46     \class QSslSocket

    47     \brief The QSslSocket class provides an SSL encrypted socket for both

    48     clients and servers.

    49     \since 4.3

    50 

    51     \reentrant

    52     \ingroup network

    53     \ingroup ssl

    54     \inmodule QtNetwork

    55 

    56     QSslSocket establishes a secure, encrypted TCP connection you can

    57     use for transmitting encrypted data. It can operate in both client

    58     and server mode, and it supports modern SSL protocols, including

    59     SSLv3 and TLSv1. By default, QSslSocket uses SSLv3, but you can

    60     change the SSL protocol by calling setProtocol() as long as you do

    61     it before the handshake has started.

    62 

    63     SSL encryption operates on top of the existing TCP stream after

    64     the socket enters the ConnectedState. There are two simple ways to

    65     establish a secure connection using QSslSocket: With an immediate

    66     SSL handshake, or with a delayed SSL handshake occurring after the

    67     connection has been established in unencrypted mode.

    68 

    69     The most common way to use QSslSocket is to construct an object

    70     and start a secure connection by calling connectToHostEncrypted().

    71     This method starts an immediate SSL handshake once the connection

    72     has been established.

    73 

    74     \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 0

    75 

    76     As with a plain QTcpSocket, QSslSocket enters the HostLookupState,

    77     ConnectingState, and finally the ConnectedState, if the connection

    78     is successful. The handshake then starts automatically, and if it

    79     succeeds, the encrypted() signal is emitted to indicate the socket

    80     has entered the encrypted state and is ready for use.

    81 

    82     Note that data can be written to the socket immediately after the

    83     return from connectToHostEncrypted() (i.e., before the encrypted()

    84     signal is emitted). The data is queued in QSslSocket until after

    85     the encrypted() signal is emitted.

    86 

    87     An example of using the delayed SSL handshake to secure an

    88     existing connection is the case where an SSL server secures an

    89     incoming connection. Suppose you create an SSL server class as a

    90     subclass of QTcpServer. You would override

    91     QTcpServer::incomingConnection() with something like the example

    92     below, which first constructs an instance of QSslSocket and then

    93     calls setSocketDescriptor() to set the new socket's descriptor to

    94     the existing one passed in. It then initiates the SSL handshake

    95     by calling startServerEncryption().

    96 

    97     \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 1

    98 

    99     If an error occurs, QSslSocket emits the sslErrors() signal. In this

   100     case, if no action is taken to ignore the error(s), the connection

   101     is dropped. To continue, despite the occurrence of an error, you

   102     can call ignoreSslErrors(), either from within this slot after the

   103     error occurs, or any time after construction of the QSslSocket and

   104     before the connection is attempted. This will allow QSslSocket to

   105     ignore the errors it encounters when establishing the identity of

   106     the peer. Ignoring errors during an SSL handshake should be used

   107     with caution, since a fundamental characteristic of secure

   108     connections is that they should be established with a successful

   109     handshake.

   110 

   111     Once encrypted, you use QSslSocket as a regular QTcpSocket. When

   112     readyRead() is emitted, you can call read(), canReadLine() and

   113     readLine(), or getChar() to read decrypted data from QSslSocket's

   114     internal buffer, and you can call write() or putChar() to write

   115     data back to the peer. QSslSocket will automatically encrypt the

   116     written data for you, and emit encryptedBytesWritten() once

   117     the data has been written to the peer.

   118 

   119     As a convenience, QSslSocket supports QTcpSocket's blocking

   120     functions waitForConnected(), waitForReadyRead(),

   121     waitForBytesWritten(), and waitForDisconnected(). It also provides

   122     waitForEncrypted(), which will block the calling thread until an

   123     encrypted connection has been established.

   124 

   125     \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 2

   126 

   127     QSslSocket provides an extensive, easy-to-use API for handling

   128     cryptographic ciphers, private keys, and local, peer, and

   129     Certification Authority (CA) certificates. It also provides an API

   130     for handling errors that occur during the handshake phase.

   131 

   132     The following features can also be customized:

   133 

   134     \list

   135     \o The socket's cryptographic cipher suite can be customized before

   136     the handshake phase with setCiphers() and setDefaultCiphers().

   137     \o The socket's local certificate and private key can be customized

   138     before the handshake phase with setLocalCertificate() and

   139     setPrivateKey().

   140     \o The CA certificate database can be extended and customized with

   141     addCaCertificate(), addCaCertificates(), setCaCertificates(),

   142     addDefaultCaCertificate(), addDefaultCaCertificates(), and

   143     setDefaultCaCertificates().

   144     \endlist

   145 

   146     For more information about ciphers and certificates, refer to QSslCipher and

   147     QSslCertificate.

   148 

   149     This product includes software developed by the OpenSSL Project

   150     for use in the OpenSSL Toolkit (\l{http://www.openssl.org/}).

   151 

   152     \note Be aware of the difference between the bytesWritten() signal and

   153     the encryptedBytesWritten() signal. For a QTcpSocket, bytesWritten()

   154     will get emitted as soon as data has been written to the TCP socket.

   155     For a QSslSocket, bytesWritten() will get emitted when the data

   156     is being encrypted and encryptedBytesWritten()

   157     will get emitted as soon as data has been written to the TCP socket.

   158 

   159     \sa QSslCertificate, QSslCipher, QSslError

   160 */

   161 

   162 /*!

   163     \enum QSslSocket::SslMode

   164 

   165     Describes the connection modes available for QSslSocket.

   166 

   167     \value UnencryptedMode The socket is unencrypted. Its

   168     behavior is identical to QTcpSocket.

   169 

   170     \value SslClientMode The socket is a client-side SSL socket.

   171     It is either alreayd encrypted, or it is in the SSL handshake

   172     phase (see QSslSocket::isEncrypted()).

   173 

   174     \value SslServerMode The socket is a server-side SSL socket.

   175     It is either already encrypted, or it is in the SSL handshake

   176     phase (see QSslSocket::isEncrypted()).

   177 */

   178 

   179 /*!

   180     \enum QSslSocket::PeerVerifyMode

   181     \since 4.4

   182 

   183     Describes the peer verification modes for QSslSocket. The default mode is

   184     AutoVerifyPeer, which selects an appropriate mode depending on the

   185     socket's QSocket::SslMode.

   186 

   187     \value VerifyNone QSslSocket will not request a certificate from the

   188     peer. You can set this mode if you are not interested in the identity of

   189     the other side of the connection. The connection will still be encrypted,

   190     and your socket will still send its local certificate to the peer if it's

   191     requested.

   192 

   193     \value QueryPeer QSslSocket will request a certificate from the peer, but

   194     does not require this certificate to be valid. This is useful when you

   195     want to display peer certificate details to the user without affecting the

   196     actual SSL handshake. This mode is the default for servers.

   197 

   198     \value VerifyPeer QSslSocket will request a certificate from the peer

   199     during the SSL handshake phase, and requires that this certificate is

   200     valid. On failure, QSslSocket will emit the QSslSocket::sslErrors()

   201     signal. This mode is the default for clients.

   202 

   203     \value AutoVerifyPeer QSslSocket will automaticaly use QueryPeer for

   204     server sockets and VerifyPeer for client sockets.

   205 

   206     \sa QSslSocket::peerVerifyMode()

   207 */

   208 

   209 /*!

   210     \fn QSslSocket::encrypted()

   211 

   212     This signal is emitted when QSslSocket enters encrypted mode. After this

   213     signal has been emitted, QSslSocket::isEncrypted() will return true, and

   214     all further transmissions on the socket will be encrypted.

   215 

   216     \sa QSslSocket::connectToHostEncrypted(), QSslSocket::isEncrypted()

   217 */

   218 

   219 /*!

   220     \fn QSslSocket::modeChanged(QSslSocket::SslMode mode)

   221 

   222     This signal is emitted when QSslSocket changes from \l

   223     QSslSocket::UnencryptedMode to either \l QSslSocket::SslClientMode or \l

   224     QSslSocket::SslServerMode. \a mode is the new mode.

   225 

   226     \sa QSslSocket::mode()

   227 */

   228 

   229 /*!

   230     \fn QSslSocket::encryptedBytesWritten(qint64 written)

   231     \since 4.4

   232 

   233     This signal is emitted when QSslSocket writes its encrypted data to the

   234     network. The \a written parameter contains the number of bytes that were

   235     successfully written.

   236 

   237     \sa QIODevice::bytesWritten()

   238 */

   239 

   240 /*!

   241     \fn void QSslSocket::peerVerifyError(const QSslError &error)

   242     \since 4.4

   243 

   244     QSslSocket can emit this signal several times during the SSL handshake,

   245     before encryption has been established, to indicate that an error has

   246     occurred while establishing the identity of the peer. The \a error is

   247     usually an indication that QSslSocket is unable to securely identify the

   248     peer.

   249 

   250     This signal provides you with an early indication when something's wrong.

   251     By connecting to this signal, you can manually choose to tear down the

   252     connection from inside the connected slot before the handshake has

   253     completed. If no action is taken, QSslSocket will proceed to emitting

   254     QSslSocket::sslErrors().

   255 

   256     \sa sslErrors()

   257 */

   258 

   259 /*!

   260     \fn void QSslSocket::sslErrors(const QList<QSslError> &errors);

   261     

   262     QSslSocket emits this signal after the SSL handshake to indicate that one

   263     or more errors have occurred while establishing the identity of the

   264     peer. The errors are usually an indication that QSslSocket is unable to

   265     securely identify the peer. Unless any action is taken, the connection

   266     will be dropped after this signal has been emitted.

   267 

   268     If you want to continue connecting despite the errors that have occurred,

   269     you must call QSslSocket::ignoreSslErrors() from inside a slot connected to

   270     this signal. If you need to access the error list at a later point, you

   271     can call sslErrors() (without arguments).

   272 

   273     \a errors contains one or more errors that prevent QSslSocket from

   274     verifying the identity of the peer.

   275     

   276     Note: You cannot use Qt::QueuedConnection when connecting to this signal,

   277     or calling QSslSocket::ignoreSslErrors() will have no effect.

   278 

   279     \sa peerVerifyError()

   280 */

   281 

   282 #include "qsslcipher.h"

   283 #include "qsslsocket.h"

   284 #include "qsslsocket_openssl_p.h"

   285 #include "qsslconfiguration_p.h"

   286 

   287 #include <QtCore/qdebug.h>

   288 #include <QtCore/qdir.h>

   289 #include <QtCore/qdatetime.h>

   290 #include <QtCore/qmutex.h>

   291 #include <QtNetwork/qhostaddress.h>

   292 #include <QtNetwork/qhostinfo.h>

   293 

   294 QT_BEGIN_NAMESPACE

   295 

   296 /*

   297    Returns the difference between msecs and elapsed. If msecs is -1,

   298    however, -1 is returned.

   299 */

   300 static int qt_timeout_value(int msecs, int elapsed)

   301 {

   302     if (msecs == -1)

   303         return -1;

   304 

   305     int timeout = msecs - elapsed;

   306     return timeout < 0 ? 0 : timeout;

   307 }

   308 

   309 class QSslSocketGlobalData

   310 {

   311 public:

   312     QSslSocketGlobalData() : config(new QSslConfigurationPrivate) {}

   313 

   314     QMutex mutex;

   315     QList<QSslCipher> supportedCiphers;

   316     QExplicitlySharedDataPointer<QSslConfigurationPrivate> config;

   317 };

   318 Q_GLOBAL_STATIC(QSslSocketGlobalData, globalData)

   319 

   320 /*!

   321     Constructs a QSslSocket object. \a parent is passed to QObject's

   322     constructor. The new socket's \l {QSslCipher} {cipher} suite is

   323     set to the one returned by the static method defaultCiphers().

   324 */

   325 QSslSocket::QSslSocket(QObject *parent)

   326     : QTcpSocket(*new QSslSocketBackendPrivate, parent)

   327 {

   328     Q_D(QSslSocket);

   329 #ifdef QSSLSOCKET_DEBUG

   330     qDebug() << "QSslSocket::QSslSocket(" << parent << "), this =" << (void *)this;

   331 #endif

   332     d->q_ptr = this;

   333     d->init();

   334 }

   335 

   336 /*!

   337     Destroys the QSslSocket.

   338 */

   339 QSslSocket::~QSslSocket()

   340 {

   341     Q_D(QSslSocket);

   342 #ifdef QSSLSOCKET_DEBUG

   343     qDebug() << "QSslSocket::~QSslSocket(), this =" << (void *)this;

   344 #endif

   345     delete d->plainSocket;

   346     d->plainSocket = 0;

   347 }

   348 

   349 /*!

   350     Starts an encrypted connection to the device \a hostName on \a

   351     port, using \a mode as the \l OpenMode. This is equivalent to

   352     calling connectToHost() to establish the connection, followed by a

   353     call to startClientEncryption().

   354 

   355     QSslSocket first enters the HostLookupState. Then, after entering

   356     either the event loop or one of the waitFor...() functions, it

   357     enters the ConnectingState, emits connected(), and then initiates

   358     the SSL client handshake. At each state change, QSslSocket emits

   359     signal stateChanged().

   360 

   361     After initiating the SSL client handshake, if the identity of the

   362     peer can't be established, signal sslErrors() is emitted. If you

   363     want to ignore the errors and continue connecting, you must call

   364     ignoreSslErrors(), either from inside a slot function connected to

   365     the sslErrors() signal, or prior to entering encrypted mode. If

   366     ignoreSslErrors() is not called, the connection is dropped, signal

   367     disconnected() is emitted, and QSslSocket returns to the

   368     UnconnectedState.

   369 

   370     If the SSL handshake is successful, QSslSocket emits encrypted().

   371 

   372     \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 3

   373 

   374     \bold{Note:} The example above shows that text can be written to

   375     the socket immediately after requesting the encrypted connection,

   376     before the encrypted() signal has been emitted. In such cases, the

   377     text is queued in the object and written to the socket \e after

   378     the connection is established and the encrypted() signal has been

   379     emitted.

   380 

   381     The default for \a mode is \l ReadWrite.

   382 

   383     If you want to create a QSslSocket on the server side of a connection, you

   384     should instead call startServerEncryption() upon receiving the incoming

   385     connection through QTcpServer.

   386 

   387     \sa connectToHost(), startClientEncryption(), waitForConnected(), waitForEncrypted()

   388 */

   389 void QSslSocket::connectToHostEncrypted(const QString &hostName, quint16 port, OpenMode mode)

   390 {

   391     Q_D(QSslSocket);

   392     if (d->state == ConnectedState || d->state == ConnectingState) {

   393         qWarning("QSslSocket::connectToHostEncrypted() called when already connecting/connected");

   394         return;

   395     }

   396 

   397     d->init();

   398     d->autoStartHandshake = true;

   399     d->initialized = true;

   400 

   401     // Note: When connecting to localhost, some platforms (e.g., HP-UX and some BSDs)

   402     // establish the connection immediately (i.e., first attempt).

   403     connectToHost(hostName, port, mode);

   404 }

   405 

   406 /*!

   407     \since 4.6

   408     \overload

   409 

   410     In addition to the original behaviour of connectToHostEncrypted,

   411     this overloaded method enables the usage of a different hostname 

   412     (\a sslPeerName) for the certificate validation instead of

   413     the one used for the TCP connection (\a hostName).

   414 

   415     \sa connectToHostEncrypted()

   416 */

   417 void QSslSocket::connectToHostEncrypted(const QString &hostName, quint16 port,

   418                                         const QString &sslPeerName, OpenMode mode)

   419 {

   420     Q_D(QSslSocket);

   421     if (d->state == ConnectedState || d->state == ConnectingState) {

   422         qWarning("QSslSocket::connectToHostEncrypted() called when already connecting/connected");

   423         return;

   424     }

   425 

   426     d->init();

   427     d->autoStartHandshake = true;

   428     d->initialized = true;

   429     d->verificationPeerName = sslPeerName;

   430 

   431     // Note: When connecting to localhost, some platforms (e.g., HP-UX and some BSDs)

   432     // establish the connection immediately (i.e., first attempt).

   433     connectToHost(hostName, port, mode);

   434 }

   435 

   436 /*!

   437     Initializes QSslSocket with the native socket descriptor \a

   438     socketDescriptor. Returns true if \a socketDescriptor is accepted

   439     as a valid socket descriptor; otherwise returns false.

   440     The socket is opened in the mode specified by \a openMode, and

   441     enters the socket state specified by \a state.

   442 

   443     \bold{Note:} It is not possible to initialize two sockets with the same

   444     native socket descriptor.

   445 

   446     \sa socketDescriptor()

   447 */

   448 bool QSslSocket::setSocketDescriptor(int socketDescriptor, SocketState state, OpenMode openMode)

   449 {

   450     Q_D(QSslSocket);

   451 #ifdef QSSLSOCKET_DEBUG

   452     qDebug() << "QSslSocket::setSocketDescriptor(" << socketDescriptor << ','

   453              << state << ',' << openMode << ')';

   454 #endif

   455     if (!d->plainSocket)

   456         d->createPlainSocket(openMode);

   457     bool retVal = d->plainSocket->setSocketDescriptor(socketDescriptor, state, openMode);

   458     d->cachedSocketDescriptor = d->plainSocket->socketDescriptor();

   459     setSocketError(d->plainSocket->error());

   460     setSocketState(state);

   461     setOpenMode(openMode);

   462     setLocalPort(d->plainSocket->localPort());

   463     setLocalAddress(d->plainSocket->localAddress());

   464     setPeerPort(d->plainSocket->peerPort());

   465     setPeerAddress(d->plainSocket->peerAddress());

   466     setPeerName(d->plainSocket->peerName());

   467     return retVal;

   468 }

   469 

   470 /*!

   471     \since 4.6

   472     Sets the given \a option to the value described by \a value.

   473 

   474     \sa socketOption()

   475 */

   476 void QSslSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value)

   477 {

   478     Q_D(QSslSocket);

   479     if (d->plainSocket)

   480         d->plainSocket->setSocketOption(option, value);

   481 }

   482 

   483 /*!

   484     \since 4.6

   485     Returns the value of the \a option option.

   486 

   487     \sa setSocketOption()

   488 */

   489 QVariant QSslSocket::socketOption(QAbstractSocket::SocketOption option)

   490 {

   491     Q_D(QSslSocket);

   492     if (d->plainSocket)

   493         return d->plainSocket->socketOption(option);

   494     else

   495         return QVariant();

   496 }

   497 

   498 /*!

   499     Returns the current mode for the socket; either UnencryptedMode, where

   500     QSslSocket behaves identially to QTcpSocket, or one of SslClientMode or

   501     SslServerMode, where the client is either negotiating or in encrypted

   502     mode.

   503 

   504     When the mode changes, QSslSocket emits modeChanged()

   505 

   506     \sa SslMode

   507 */

   508 QSslSocket::SslMode QSslSocket::mode() const

   509 {

   510     Q_D(const QSslSocket);

   511     return d->mode;

   512 }

   513 

   514 /*!

   515     Returns true if the socket is encrypted; otherwise, false is returned.

   516 

   517     An encrypted socket encrypts all data that is written by calling write()

   518     or putChar() before the data is written to the network, and decrypts all

   519     incoming data as the data is received from the network, before you call

   520     read(), readLine() or getChar().

   521 

   522     QSslSocket emits encrypted() when it enters encrypted mode.

   523 

   524     You can call sessionCipher() to find which cryptographic cipher is used to

   525     encrypt and decrypt your data.

   526 

   527     \sa mode()

   528 */

   529 bool QSslSocket::isEncrypted() const

   530 {

   531     Q_D(const QSslSocket);

   532     return d->connectionEncrypted;

   533 }

   534 

   535 /*!

   536     Returns the socket's SSL protocol. By default, \l QSsl::SslV3 is used.

   537 

   538     \sa setProtocol()

   539 */

   540 QSsl::SslProtocol QSslSocket::protocol() const

   541 {

   542     Q_D(const QSslSocket);

   543     return d->configuration.protocol;

   544 }

   545 

   546 /*!

   547     Sets the socket's SSL protocol to \a protocol. This will affect the next

   548     initiated handshake; calling this function on an already-encrypted socket

   549     will not affect the socket's protocol.

   550 */

   551 void QSslSocket::setProtocol(QSsl::SslProtocol protocol)

   552 {

   553     Q_D(QSslSocket);

   554     d->configuration.protocol = protocol;

   555 }

   556 

   557 /*!

   558     \since 4.4

   559 

   560     Returns the socket's verify mode. This mode mode decides whether

   561     QSslSocket should request a certificate from the peer (i.e., the client

   562     requests a certificate from the server, or a server requesting a

   563     certificate from the client), and whether it should require that this

   564     certificate is valid.

   565 

   566     The default mode is AutoVerifyPeer, which tells QSslSocket to use

   567     VerifyPeer for clients, QueryPeer for clients.

   568 

   569     \sa setPeerVerifyMode(), peerVerifyDepth(), mode()

   570 */

   571 QSslSocket::PeerVerifyMode QSslSocket::peerVerifyMode() const

   572 {

   573     Q_D(const QSslSocket);

   574     return d->configuration.peerVerifyMode;

   575 }

   576 

   577 /*!

   578     \since 4.4

   579 

   580     Sets the socket's verify mode to \a mode. This mode decides whether

   581     QSslSocket should request a certificate from the peer (i.e., the client

   582     requests a certificate from the server, or a server requesting a

   583     certificate from the client), and whether it should require that this

   584     certificate is valid.

   585 

   586     The default mode is AutoVerifyPeer, which tells QSslSocket to use

   587     VerifyPeer for clients, QueryPeer for clients.

   588 

   589     Setting this mode after encryption has started has no effect on the

   590     current connection.

   591 

   592     \sa peerVerifyMode(), setPeerVerifyDepth(), mode()

   593 */

   594 void QSslSocket::setPeerVerifyMode(QSslSocket::PeerVerifyMode mode)

   595 {

   596     Q_D(QSslSocket);

   597     d->configuration.peerVerifyMode = mode;

   598 }

   599 

   600 /*!

   601     \since 4.4

   602 

   603     Returns the maximum number of certificates in the peer's certificate chain

   604     to be checked during the SSL handshake phase, or 0 (the default) if no

   605     maximum depth has been set, indicating that the whole certificate chain

   606     should be checked.

   607 

   608     The certificates are checked in issuing order, starting with the peer's

   609     own certificate, then its issuer's certificate, and so on.

   610 

   611     \sa setPeerVerifyDepth(), peerVerifyMode()

   612 */

   613 int QSslSocket::peerVerifyDepth() const

   614 {

   615     Q_D(const QSslSocket);

   616     return d->configuration.peerVerifyDepth;

   617 }

   618 

   619 /*!

   620     \since 4.4

   621 

   622     Sets the maximum number of certificates in the peer's certificate chain to

   623     be checked during the SSL handshake phase, to \a depth. Setting a depth of

   624     0 means that no maximum depth is set, indicating that the whole

   625     certificate chain should be checked.

   626 

   627     The certificates are checked in issuing order, starting with the peer's

   628     own certificate, then its issuer's certificate, and so on.

   629 

   630     \sa peerVerifyDepth(), setPeerVerifyMode()

   631 */

   632 void QSslSocket::setPeerVerifyDepth(int depth)

   633 {

   634     Q_D(QSslSocket);

   635     if (depth < 0) {

   636         qWarning("QSslSocket::setPeerVerifyDepth: cannot set negative depth of %d", depth);

   637         return;

   638     }

   639     d->configuration.peerVerifyDepth = depth;

   640 }

   641 

   642 /*!

   643     \reimp

   644 

   645     Returns the number of decrypted bytes that are immediately available for

   646     reading.

   647 */

   648 qint64 QSslSocket::bytesAvailable() const

   649 {

   650     Q_D(const QSslSocket);

   651     if (d->mode == UnencryptedMode)

   652         return QIODevice::bytesAvailable() + (d->plainSocket ? d->plainSocket->bytesAvailable() : 0);

   653     return QIODevice::bytesAvailable() + d->readBuffer.size();

   654 }

   655 

   656 /*!

   657     \reimp

   658 

   659     Returns the number of unencrypted bytes that are waiting to be encrypted

   660     and written to the network.

   661 */

   662 qint64 QSslSocket::bytesToWrite() const

   663 {

   664     Q_D(const QSslSocket);

   665     if (d->mode == UnencryptedMode)

   666         return d->plainSocket ? d->plainSocket->bytesToWrite() : 0;

   667     return d->writeBuffer.size();

   668 }

   669 

   670 /*!

   671     \since 4.4

   672 

   673     Returns the number of encrypted bytes that are awaiting decryption.

   674     Normally, this function will return 0 because QSslSocket decrypts its

   675     incoming data as soon as it can.

   676 */

   677 qint64 QSslSocket::encryptedBytesAvailable() const

   678 {

   679     Q_D(const QSslSocket);

   680     if (d->mode == UnencryptedMode)

   681         return 0;

   682     return d->plainSocket->bytesAvailable();

   683 }

   684 

   685 /*!

   686     \since 4.4

   687 

   688     Returns the number of encrypted bytes that are waiting to be written to

   689     the network.

   690 */

   691 qint64 QSslSocket::encryptedBytesToWrite() const

   692 {

   693     Q_D(const QSslSocket);

   694     if (d->mode == UnencryptedMode)

   695         return 0;

   696     return d->plainSocket->bytesToWrite();

   697 }

   698 

   699 /*!

   700     \reimp

   701 

   702     Returns true if you can read one while line (terminated by a single ASCII

   703     '\n' character) of decrypted characters; otherwise, false is returned.

   704 */

   705 bool QSslSocket::canReadLine() const

   706 {

   707     Q_D(const QSslSocket);

   708     if (d->mode == UnencryptedMode)

   709         return QIODevice::canReadLine() || (d->plainSocket && d->plainSocket->canReadLine());

   710     return QIODevice::canReadLine() || (!d->readBuffer.isEmpty() && d->readBuffer.canReadLine());

   711 }

   712 

   713 /*!

   714     \reimp

   715 */

   716 void QSslSocket::close()

   717 {

   718 #ifdef QSSLSOCKET_DEBUG

   719     qDebug() << "QSslSocket::close()";

   720 #endif

   721     Q_D(QSslSocket);

   722     if (d->plainSocket)

   723         d->plainSocket->close();

   724     QTcpSocket::close();

   725 

   726     // must be cleared, reading/writing not possible on closed socket:

   727     d->readBuffer.clear();

   728     d->writeBuffer.clear();

   729     // for QTcpSocket this is already done because it uses the readBuffer/writeBuffer

   730     // if the QIODevice it is based on

   731     // ### FIXME QSslSocket should probably do similar instead of having

   732     // its own readBuffer/writeBuffer

   733 }

   734 

   735 /*!

   736     \reimp

   737 */

   738 bool QSslSocket::atEnd() const

   739 {

   740     Q_D(const QSslSocket);

   741     if (d->mode == UnencryptedMode)

   742         return QIODevice::atEnd() && (!d->plainSocket || d->plainSocket->atEnd());

   743     return QIODevice::atEnd() && d->readBuffer.isEmpty();

   744 }

   745 

   746 /*!

   747     This function writes as much as possible from the internal write buffer to

   748     the underlying network socket, without blocking. If any data was written,

   749     this function returns true; otherwise false is returned.

   750 

   751     Call this function if you need QSslSocket to start sending buffered data

   752     immediately. The number of bytes successfully written depends on the

   753     operating system. In most cases, you do not need to call this function,

   754     because QAbstractSocket will start sending data automatically once control

   755     goes back to the event loop. In the absence of an event loop, call

   756     waitForBytesWritten() instead.

   757 

   758     \sa write(), waitForBytesWritten()

   759 */

   760 // Note! docs copied from QAbstractSocket::flush()

   761 bool QSslSocket::flush()

   762 {

   763     Q_D(QSslSocket);

   764 #ifdef QSSLSOCKET_DEBUG

   765     qDebug() << "QSslSocket::flush()";

   766 #endif

   767     if (d->mode != UnencryptedMode)

   768         // encrypt any unencrypted bytes in our buffer

   769         d->transmit();

   770 

   771     return d->plainSocket ? d->plainSocket->flush() : false;

   772 }

   773 

   774 /*!

   775     \since 4.4

   776 

   777     Sets the size of QSslSocket's internal read buffer to be \a size bytes. 

   778 */

   779 void QSslSocket::setReadBufferSize(qint64 size)

   780 {

   781     Q_D(QSslSocket);

   782     d->readBufferMaxSize = size;

   783 

   784     // set the plain socket's buffer size to 1k if we have a limit

   785     // see also the same logic in QSslSocketPrivate::createPlainSocket

   786     if (d->plainSocket) {

   787         if (d->mode == UnencryptedMode)

   788             d->plainSocket->setReadBufferSize(size);

   789         else

   790             d->plainSocket->setReadBufferSize(size ? 1024 : 0);

   791     }

   792 }

   793 

   794 /*!

   795     Aborts the current connection and resets the socket. Unlike

   796     disconnectFromHost(), this function immediately closes the socket,

   797     clearing any pending data in the write buffer.

   798 

   799     \sa disconnectFromHost(), close()

   800 */

   801 void QSslSocket::abort()

   802 {

   803     Q_D(QSslSocket);

   804 #ifdef QSSLSOCKET_DEBUG

   805     qDebug() << "QSslSocket::abort()";

   806 #endif

   807     if (d->plainSocket)

   808         d->plainSocket->abort();

   809     close();

   810 }

   811 

   812 /*!

   813     \since 4.4

   814 

   815     Returns the socket's SSL configuration state. The default SSL

   816     configuration of a socket is to use the default ciphers,

   817     default CA certificates, no local private key or certificate.

   818 

   819     The SSL configuration also contains fields that can change with

   820     time without notice.

   821 

   822     \sa localCertificate(), peerCertificate(), peerCertificateChain(),

   823         sessionCipher(), privateKey(), ciphers(), caCertificates()

   824 */

   825 QSslConfiguration QSslSocket::sslConfiguration() const

   826 {

   827     Q_D(const QSslSocket);

   828 

   829     // create a deep copy of our configuration

   830     QSslConfigurationPrivate *copy = new QSslConfigurationPrivate(d->configuration);

   831     copy->ref = 0;              // the QSslConfiguration constructor refs up

   832     copy->sessionCipher = d->sessionCipher();

   833 

   834     return QSslConfiguration(copy);

   835 }

   836 

   837 /*!

   838     \since 4.4

   839 

   840     Sets the socket's SSL configuration to be the contents of \a configuration.

   841     This function sets the local certificate, the ciphers, the private key and the CA

   842     certificates to those stored in \a configuration.

   843 

   844     It is not possible to set the SSL-state related fields.

   845 

   846     \sa setLocalCertificate(), setPrivateKey(), setCaCertificates(), setCiphers()

   847 */

   848 void QSslSocket::setSslConfiguration(const QSslConfiguration &configuration)

   849 {

   850     Q_D(QSslSocket);

   851     d->configuration.localCertificate = configuration.localCertificate();

   852     d->configuration.privateKey = configuration.privateKey();

   853     d->configuration.ciphers = configuration.ciphers();

   854     d->configuration.caCertificates = configuration.caCertificates();

   855     d->configuration.peerVerifyDepth = configuration.peerVerifyDepth();

   856     d->configuration.peerVerifyMode = configuration.peerVerifyMode();

   857     d->configuration.protocol = configuration.protocol();

   858 }

   859 

   860 /*!

   861     Sets the socket's local certificate to \a certificate. The local

   862     certificate is necessary if you need to confirm your identity to the

   863     peer. It is used together with the private key; if you set the local

   864     certificate, you must also set the private key.

   865 

   866     The local certificate and private key are always necessary for server

   867     sockets, but are also rarely used by client sockets if the server requires

   868     the client to authenticate.

   869 

   870     \sa localCertificate(), setPrivateKey()

   871 */

   872 void QSslSocket::setLocalCertificate(const QSslCertificate &certificate)

   873 {

   874     Q_D(QSslSocket);

   875     d->configuration.localCertificate = certificate;

   876 }

   877 

   878 /*!

   879     \overload

   880 

   881     Sets the socket's local \l {QSslCertificate} {certificate} to the

   882     first one found in file \a path, which is parsed according to the 

   883     specified \a format.

   884 */

   885 void QSslSocket::setLocalCertificate(const QString &path,

   886                                      QSsl::EncodingFormat format)

   887 {

   888     Q_D(QSslSocket);

   889     QFile file(path);

   890     if (file.open(QIODevice::ReadOnly | QIODevice::Text))

   891         d->configuration.localCertificate = QSslCertificate(file.readAll(), format);

   892 }

   893 

   894 /*!

   895     Returns the socket's local \l {QSslCertificate} {certificate}, or

   896     an empty certificate if no local certificate has been assigned.

   897 

   898     \sa setLocalCertificate(), privateKey()

   899 */

   900 QSslCertificate QSslSocket::localCertificate() const

   901 {

   902     Q_D(const QSslSocket);

   903     return d->configuration.localCertificate;

   904 }

   905 

   906 /*!

   907     Returns the peer's digital certificate (i.e., the immediate

   908     certificate of the host you are connected to), or a null

   909     certificate, if the peer has not assigned a certificate.

   910     

   911     The peer certificate is checked automatically during the

   912     handshake phase, so this function is normally used to fetch

   913     the certificate for display or for connection diagnostic

   914     purposes. It contains information about the peer, including

   915     its host name, the certificate issuer, and the peer's public

   916     key.

   917 

   918     Because the peer certificate is set during the handshake phase, it

   919     is safe to access the peer certificate from a slot connected to

   920     the sslErrors() signal or the encrypted() signal.

   921 

   922     If a null certificate is returned, it can mean the SSL handshake

   923     failed, or it can mean the host you are connected to doesn't have

   924     a certificate, or it can mean there is no connection.

   925 

   926     If you want to check the peer's complete chain of certificates,

   927     use peerCertificateChain() to get them all at once.

   928 

   929     \sa peerCertificateChain()

   930 */

   931 QSslCertificate QSslSocket::peerCertificate() const

   932 {

   933     Q_D(const QSslSocket);

   934     return d->configuration.peerCertificate;

   935 }

   936 

   937 /*!

   938     Returns the peer's chain of digital certificates, or an empty list

   939     of certificates.

   940 

   941     Peer certificates are checked automatically during the handshake

   942     phase. This function is normally used to fetch certificates for

   943     display, or for performing connection diagnostics. Certificates

   944     contain information about the peer and the certificate issuers,

   945     including host name, issuer names, and issuer public keys.

   946 

   947     The peer certificates are set in QSslSocket during the handshake

   948     phase, so it is safe to call this function from a slot connected

   949     to the sslErrors() signal or the encrypted() signal.

   950 

   951     If an empty list is returned, it can mean the SSL handshake

   952     failed, or it can mean the host you are connected to doesn't have

   953     a certificate, or it can mean there is no connection.

   954 

   955     If you want to get only the peer's immediate certificate, use

   956     peerCertificate().

   957 

   958     \sa peerCertificate()

   959 */

   960 QList<QSslCertificate> QSslSocket::peerCertificateChain() const

   961 {

   962     Q_D(const QSslSocket);

   963     return d->configuration.peerCertificateChain;

   964 }

   965 

   966 /*!

   967     Returns the socket's cryptographic \l {QSslCipher} {cipher}, or a

   968     null cipher if the connection isn't encrypted. The socket's cipher

   969     for the session is set during the handshake phase. The cipher is

   970     used to encrypt and decrypt data transmitted through the socket.

   971 

   972     QSslSocket also provides functions for setting the ordered list of

   973     ciphers from which the handshake phase will eventually select the

   974     session cipher. This ordered list must be in place before the

   975     handshake phase begins.

   976 

   977     \sa ciphers(), setCiphers(), setDefaultCiphers(), defaultCiphers(),

   978     supportedCiphers()

   979 */

   980 QSslCipher QSslSocket::sessionCipher() const

   981 {

   982     Q_D(const QSslSocket);

   983     return d->sessionCipher();

   984 }

   985 

   986 /*!

   987     Sets the socket's private \l {QSslKey} {key} to \a key. The

   988     private key and the local \l {QSslCertificate} {certificate} are

   989     used by clients and servers that must prove their identity to

   990     SSL peers.

   991 

   992     Both the key and the local certificate are required if you are

   993     creating an SSL server socket. If you are creating an SSL client

   994     socket, the key and local certificate are required if your client

   995     must identify itself to an SSL server.

   996 

   997     \sa privateKey(), setLocalCertificate()

   998 */

   999 void QSslSocket::setPrivateKey(const QSslKey &key)

  1000 {

  1001     Q_D(QSslSocket);

  1002     d->configuration.privateKey = key;

  1003 }

  1004 

  1005 /*!

  1006     \overload

  1007 

  1008     Reads the string in file \a fileName and decodes it using

  1009     a specified \a algorithm and encoding \a format to construct

  1010     an \l {QSslKey} {SSL key}. If the encoded key is encrypted,

  1011     \a passPhrase is used to decrypt it.

  1012 

  1013     The socket's private key is set to the constructed key. The

  1014     private key and the local \l {QSslCertificate} {certificate} are

  1015     used by clients and servers that must prove their identity to SSL

  1016     peers.

  1017 

  1018     Both the key and the local certificate are required if you are

  1019     creating an SSL server socket. If you are creating an SSL client

  1020     socket, the key and local certificate are required if your client

  1021     must identify itself to an SSL server.

  1022     

  1023     \sa privateKey(), setLocalCertificate()

  1024 */

  1025 void QSslSocket::setPrivateKey(const QString &fileName, QSsl::KeyAlgorithm algorithm,

  1026                                QSsl::EncodingFormat format, const QByteArray &passPhrase)

  1027 {

  1028     Q_D(QSslSocket);

  1029     QFile file(fileName);

  1030     if (file.open(QIODevice::ReadOnly)) {

  1031         d->configuration.privateKey = QSslKey(file.readAll(), algorithm,

  1032                                               format, QSsl::PrivateKey, passPhrase);

  1033     }

  1034 }

  1035 

  1036 /*!

  1037     Returns this socket's private key.

  1038 

  1039     \sa setPrivateKey(), localCertificate()

  1040 */

  1041 QSslKey QSslSocket::privateKey() const

  1042 {

  1043     Q_D(const QSslSocket);

  1044     return d->configuration.privateKey;

  1045 }

  1046 

  1047 /*!

  1048     Returns this socket's current cryptographic cipher suite. This

  1049     list is used during the socket's handshake phase for choosing a

  1050     session cipher. The returned list of ciphers is ordered by

  1051     descending preference. (i.e., the first cipher in the list is the

  1052     most preferred cipher). The session cipher will be the first one

  1053     in the list that is also supported by the peer.

  1054 

  1055     By default, the handshake phase can choose any of the ciphers

  1056     supported by this system's SSL libraries, which may vary from

  1057     system to system. The list of ciphers supported by this system's

  1058     SSL libraries is returned by supportedCiphers(). You can restrict

  1059     the list of ciphers used for choosing the session cipher for this

  1060     socket by calling setCiphers() with a subset of the supported

  1061     ciphers. You can revert to using the entire set by calling

  1062     setCiphers() with the list returned by supportedCiphers().

  1063 

  1064     You can restrict the list of ciphers used for choosing the session

  1065     cipher for \e all sockets by calling setDefaultCiphers() with a

  1066     subset of the supported ciphers. You can revert to using the

  1067     entire set by calling setCiphers() with the list returned by

  1068     supportedCiphers().

  1069 

  1070     \sa setCiphers(), defaultCiphers(), setDefaultCiphers(), supportedCiphers()

  1071 */

  1072 QList<QSslCipher> QSslSocket::ciphers() const

  1073 {

  1074     Q_D(const QSslSocket);

  1075     return d->configuration.ciphers;

  1076 }

  1077 

  1078 /*!

  1079     Sets the cryptographic cipher suite for this socket to \a ciphers,

  1080     which must contain a subset of the ciphers in the list returned by

  1081     supportedCiphers().

  1082 

  1083     Restricting the cipher suite must be done before the handshake

  1084     phase, where the session cipher is chosen.

  1085 

  1086     \sa ciphers(), setDefaultCiphers(), supportedCiphers()

  1087 */

  1088 void QSslSocket::setCiphers(const QList<QSslCipher> &ciphers)

  1089 {

  1090     Q_D(QSslSocket);

  1091     d->configuration.ciphers = ciphers;

  1092 }

  1093 

  1094 /*!

  1095     Sets the cryptographic cipher suite for this socket to \a ciphers, which

  1096     is a colon-separated list of cipher suite names. The ciphers are listed in

  1097     order of preference, starting with the most preferred cipher. For example:

  1098 

  1099     \snippet doc/src/snippets/code/src_network_ssl_qsslsocket.cpp 4

  1100 

  1101     Each cipher name in \a ciphers must be the name of a cipher in the

  1102     list returned by supportedCiphers().  Restricting the cipher suite

  1103     must be done before the handshake phase, where the session cipher

  1104     is chosen.

  1105 

  1106     \sa ciphers(), setDefaultCiphers(), supportedCiphers()

  1107 */

  1108 void QSslSocket::setCiphers(const QString &ciphers)

  1109 {

  1110     Q_D(QSslSocket);

  1111     d->configuration.ciphers.clear();

  1112     foreach (const QString &cipherName, ciphers.split(QLatin1String(":"),QString::SkipEmptyParts)) {

  1113         for (int i = 0; i < 3; ++i) {

  1114             // ### Crude

  1115             QSslCipher cipher(cipherName, QSsl::SslProtocol(i));

  1116             if (!cipher.isNull())

  1117                 d->configuration.ciphers << cipher;

  1118         }

  1119     }

  1120 }

  1121 

  1122 /*!

  1123     Sets the default cryptographic cipher suite for all sockets in

  1124     this application to \a ciphers, which must contain a subset of the

  1125     ciphers in the list returned by supportedCiphers().

  1126 

  1127     Restricting the default cipher suite only affects SSL sockets

  1128     that perform their handshake phase after the default cipher

  1129     suite has been changed.

  1130 

  1131     \sa setCiphers(), defaultCiphers(), supportedCiphers()

  1132 */

  1133 void QSslSocket::setDefaultCiphers(const QList<QSslCipher> &ciphers)

  1134 {

  1135     QSslSocketPrivate::setDefaultCiphers(ciphers);