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

     2 **

     3 ** Copyright (C) 2009 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 #include "qsslconfiguration.h"

    43 #include "qsslconfiguration_p.h"

    44 #include "qsslsocket.h"

    45 #include "qmutex.h"

    46 #include "qdebug.h"

    47 

    48 QT_BEGIN_NAMESPACE

    49 

    50 template<> void QSharedDataPointer<QSslConfigurationPrivate>::detach()

    51 {

    52     if (d && d->ref == 1)

    53         return;

    54     QSslConfigurationPrivate *x = (d ? new QSslConfigurationPrivate(*d)

    55                                    : new QSslConfigurationPrivate);

    56     x->ref.ref();

    57     if (d && !d->ref.deref())

    58         delete d;

    59     d = x;

    60 }

    61 

    62 /*!

    63     \class QSslConfiguration

    64     \brief The QSslConfiguration class holds the configuration and state of an SSL connection

    65     \since 4.4

    66 

    67     \reentrant

    68     \inmodule QtNetwork

    69     \ingroup network

    70     \ingroup ssl

    71 

    72     QSslConfiguration is used by Qt networking classes to relay

    73     information about an open SSL connection and to allow the

    74     application to control certain features of that connection.

    75 

    76     The settings that QSslConfiguration currently supports are:

    77 

    78     \list

    79       \o The SSL/TLS protocol to be used

    80       \o The certificate to be presented to the peer during connection

    81          and its associated private key

    82       \o The ciphers allowed to be used for encrypting the connection

    83       \o The list of Certificate Authorities certificates that are

    84          used to validate the peer's certificate

    85     \endlist

    86 

    87     These settings are applied only during the connection

    88     handshake. Setting them after the connection has been established

    89     has no effect.

    90 

    91     The state that QSslConfiguration supports are:

    92     \list

    93       \o The certificate the peer presented during handshake, along

    94          with the chain leading to a CA certificate

    95       \o The cipher used to encrypt this session

    96     \endlist

    97 

    98     The state can only be obtained once the SSL connection starts, but

    99     not necessarily before it's done. Some settings may change during

   100     the course of the SSL connection without need to restart it (for

   101     instance, the cipher can be changed over time).

   102 

   103     State in QSslConfiguration objects cannot be changed.

   104 

   105     QSslConfiguration can be used with QSslSocket and the Network

   106     Access API.

   107 

   108     Note that changing settings in QSslConfiguration is not enough to

   109     change the settings in the related SSL connection. You must call

   110     setSslConfiguration on a modified QSslConfiguration object to

   111     achieve that. The following example illustrates how to change the

   112     protocol to TLSv1 in a QSslSocket object:

   113 

   114     \snippet doc/src/snippets/code/src_network_ssl_qsslconfiguration.cpp 0

   115 

   116     \sa QSsl::SslProtocol, QSslCertificate, QSslCipher, QSslKey

   117         QSslSocket, QNetworkAccessManager,

   118         QSslSocket::sslConfiguration(), QSslSocket::setSslConfiguration()

   119 */

   120 

   121 /*!

   122     Constructs an empty SSL configuration. This configuration contains

   123     no valid settings and the state will be empty. isNull() will

   124     return true after this constructor is called.

   125 

   126     Once any setter methods are called, isNull() will return false.

   127 */

   128 QSslConfiguration::QSslConfiguration()

   129     : d(0)

   130 {

   131 }

   132 

   133 /*!

   134     Copies the configuration and state of \a other. If \a other is

   135     null, this object will be null too.

   136 */

   137 QSslConfiguration::QSslConfiguration(const QSslConfiguration &other)

   138     : d(other.d)

   139 {

   140 }

   141 

   142 /*!

   143     Releases any resources held by QSslConfiguration.

   144 */

   145 QSslConfiguration::~QSslConfiguration()

   146 {

   147     // QSharedDataPointer deletes d for us if necessary

   148 }

   149 

   150 /*!

   151     Copies the configuration and state of \a other. If \a other is

   152     null, this object will be null too.

   153 */

   154 QSslConfiguration &QSslConfiguration::operator=(const QSslConfiguration &other)

   155 {

   156     d = other.d;

   157     return *this;

   158 }

   159 

   160 /*!

   161     Returns true if this QSslConfiguration object is equal to \a

   162     other.

   163 

   164     Two QSslConfiguration objects are considered equal if they have

   165     the exact same settings and state.

   166 

   167     \sa operator!=()

   168 */

   169 bool QSslConfiguration::operator==(const QSslConfiguration &other) const

   170 {

   171     if (d == other.d)

   172         return true;

   173     return d->peerCertificate == other.d->peerCertificate &&

   174         d->peerCertificateChain == other.d->peerCertificateChain &&

   175         d->localCertificate == other.d->localCertificate &&

   176         d->privateKey == other.d->privateKey &&

   177         d->sessionCipher == other.d->sessionCipher &&

   178         d->ciphers == other.d->ciphers &&

   179         d->caCertificates == d->caCertificates &&

   180         d->protocol == other.d->protocol &&

   181         d->peerVerifyMode == other.d->peerVerifyMode &&

   182         d->peerVerifyDepth == other.d->peerVerifyDepth;

   183 }

   184 

   185 /*!

   186     \fn QSslConfiguration::operator!=(const QSslConfiguration &other) const

   187 

   188     Returns true if this QSslConfiguration differs from \a other. Two

   189     QSslConfiguration objects are considered different if any state or

   190     setting is different.

   191 

   192     \sa operator==()

   193 */

   194 

   195 /*!

   196     Returns true if this is a null QSslConfiguration object.

   197 

   198     A QSslConfiguration object is null if it has been

   199     default-constructed and no setter methods have been called.

   200 

   201     \sa setProtocol(), setLocalCertificate(), setPrivateKey(),

   202         setCiphers(), setCaCertificates()

   203 */

   204 bool QSslConfiguration::isNull() const

   205 {

   206     return d == 0;

   207 }

   208 

   209 /*!

   210     Returns the protocol setting for this SSL configuration.

   211 

   212     \sa setProtocol()

   213 */

   214 QSsl::SslProtocol QSslConfiguration::protocol() const

   215 {

   216     return d ? d->protocol : QSsl::SslV3;

   217 }

   218 

   219 /*!

   220     Sets the protocol setting for this configuration to be \a

   221     protocol.

   222 

   223     Setting the protocol once the connection has already been

   224     established has no effect.

   225 

   226     \sa protocol()

   227 */

   228 void QSslConfiguration::setProtocol(QSsl::SslProtocol protocol)

   229 {

   230     d->protocol = protocol;

   231 }

   232 

   233 /*!

   234     Returns the verify mode. This mode decides whether QSslSocket should

   235     request a certificate from the peer (i.e., the client requests a

   236     certificate from the server, or a server requesting a certificate from the

   237     client), and whether it should require that this certificate is valid.

   238 

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

   240     VerifyPeer for clients, QueryPeer for clients.

   241 

   242     \sa setPeerVerifyMode()

   243 */

   244 QSslSocket::PeerVerifyMode QSslConfiguration::peerVerifyMode() const

   245 {

   246     return d ? d->peerVerifyMode : QSslSocket::AutoVerifyPeer;

   247 }

   248 

   249 /*!

   250     Sets the verify mode to \a mode. This mode decides whether QSslSocket

   251     should request a certificate from the peer (i.e., the client requests a

   252     certificate from the server, or a server requesting a certificate from the

   253     client), and whether it should require that this certificate is valid.

   254 

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

   256     VerifyPeer for clients, QueryPeer for clients.

   257 

   258     \sa peerVerifyMode()

   259 */

   260 void QSslConfiguration::setPeerVerifyMode(QSslSocket::PeerVerifyMode mode)

   261 {

   262     d->peerVerifyMode = mode;

   263 }

   264 

   265 

   266 /*!

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

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

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

   270     should be checked.

   271 

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

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

   274 

   275     \sa setPeerVerifyDepth(), peerVerifyMode()

   276 */

   277 int QSslConfiguration::peerVerifyDepth() const

   278 {

   279     return d ? d->peerVerifyDepth : 0;

   280 }

   281 

   282 /*!

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

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

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

   286     certificate chain should be checked.

   287 

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

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

   290 

   291     \sa peerVerifyDepth(), setPeerVerifyMode()

   292 */

   293 void QSslConfiguration::setPeerVerifyDepth(int depth)

   294 {

   295     if (depth < 0) {

   296         qWarning("QSslConfiguration::setPeerVerifyDepth: cannot set negative depth of %d", depth);

   297         return;

   298     }

   299     d->peerVerifyDepth = depth;

   300 }

   301 

   302 /*!

   303     Returns the certificate to be presented to the peer during the SSL

   304     handshake process.

   305 

   306     \sa setLocalCertificate()

   307 */

   308 QSslCertificate QSslConfiguration::localCertificate() const

   309 {

   310     return d ? d->localCertificate : QSslCertificate();

   311 }

   312 

   313 /*!

   314     Sets the certificate to be presented to the peer during SSL

   315     handshake to be \a certificate.

   316 

   317     Setting the certificate once the connection has been established

   318     has no effect.

   319 

   320     A certificate is the means of identification used in the SSL

   321     process. The local certificate is used by the remote end to verify

   322     the local user's identity against its list of Certification

   323     Authorities. In most cases, such as in HTTP web browsing, only

   324     servers identify to the clients, so the client does not send a

   325     certificate.

   326 

   327     \sa localCertificate()

   328 */

   329 void QSslConfiguration::setLocalCertificate(const QSslCertificate &certificate)

   330 {

   331     d->localCertificate = certificate;

   332 }

   333 

   334 /*!

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

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

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

   338 

   339     The peer certificate is checked automatically during the

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

   341     the certificate for display or for connection diagnostic

   342     purposes. It contains information about the peer, including

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

   344     key.

   345 

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

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

   348     the QSslSocket::sslErrors() signal, QNetworkReply::sslErrors()

   349     signal, or the QSslSocket::encrypted() signal.

   350 

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

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

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

   354 

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

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

   357 

   358     \sa peerCertificateChain(),

   359         QSslSocket::sslErrors(), QSslSocket::ignoreSslErrors(),

   360         QNetworkReply::sslErrors(), QNetworkReply::ignoreSslErrors()

   361 */

   362 QSslCertificate QSslConfiguration::peerCertificate() const

   363 {

   364     return d ? d->peerCertificate : QSslCertificate();

   365 }

   366 

   367 /*!

   368     Returns the peer's chain of digital certificates, starting with

   369     the peer's immediate certificate and ending with the CA's

   370     certificate.

   371 

   372     Peer certificates are checked automatically during the handshake

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

   374     display, or for performing connection diagnostics. Certificates

   375     contain information about the peer and the certificate issuers,

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

   377 

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

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

   380     the QSslSocket::sslErrors() signal, QNetworkReply::sslErrors()

   381     signal, or the QSslSocket::encrypted() signal.

   382 

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

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

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

   386 

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

   388     peerCertificate().

   389 

   390     \sa peerCertificate(),

   391         QSslSocket::sslErrors(), QSslSocket::ignoreSslErrors(),

   392         QNetworkReply::sslErrors(), QNetworkReply::ignoreSslErrors()

   393 */

   394 QList<QSslCertificate> QSslConfiguration::peerCertificateChain() const

   395 {

   396     return d ? d->peerCertificateChain : QList<QSslCertificate>();

   397 }

   398 

   399 /*!

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

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

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

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

   404 

   405     The SSL infrastructure also provides functions for setting the

   406     ordered list of ciphers from which the handshake phase will

   407     eventually select the session cipher. This ordered list must be in

   408     place before the handshake phase begins.

   409 

   410     \sa ciphers(), setCiphers(), QSslSocket::supportedCiphers()

   411 */

   412 QSslCipher QSslConfiguration::sessionCipher() const

   413 {

   414     return d ? d->sessionCipher : QSslCipher();

   415 }

   416 

   417 /*!

   418     Returns the \l {QSslKey} {SSL key} assigned to this connection or

   419     a null key if none has been assigned yet.

   420 

   421     \sa setPrivateKey(), localCertificate()

   422 */

   423 QSslKey QSslConfiguration::privateKey() const

   424 {

   425     return d ? d->privateKey : QSslKey();

   426 }

   427 

   428 /*!

   429     Sets the connection's private \l {QSslKey} {key} to \a key. The

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

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

   432     SSL peers.

   433 

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

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

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

   437     must identify itself to an SSL server.

   438 

   439     \sa privateKey(), setLocalCertificate()

   440 */

   441 void QSslConfiguration::setPrivateKey(const QSslKey &key)

   442 {

   443     d->privateKey = key;

   444 }

   445 

   446 /*!

   447     Returns this connection's current cryptographic cipher suite. This

   448     list is used during the handshake phase for choosing a

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

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

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

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

   453 

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

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

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

   457     SSL libraries is returned by QSslSocket::supportedCiphers(). You can restrict

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

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

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

   461     setCiphers() with the list returned by QSslSocket::supportedCiphers().

   462 

   463     \sa setCiphers(), QSslSocket::supportedCiphers()

   464 */

   465 QList<QSslCipher> QSslConfiguration::ciphers() const

   466 {

   467     return d ? d->ciphers : QList<QSslCipher>();

   468 }

   469 

   470 /*!

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

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

   473     supportedCiphers().

   474 

   475     Restricting the cipher suite must be done before the handshake

   476     phase, where the session cipher is chosen.

   477 

   478     \sa ciphers(), QSslSocket::supportedCiphers()

   479 */

   480 void QSslConfiguration::setCiphers(const QList<QSslCipher> &ciphers)

   481 {

   482     d->ciphers = ciphers;

   483 }

   484 

   485 /*!

   486   Returns this connection's CA certificate database. The CA certificate

   487   database is used by the socket during the handshake phase to

   488   validate the peer's certificate. It can be moodified prior to the

   489   handshake with addCaCertificate(), addCaCertificates(), and

   490   setCaCertificates().

   491 

   492   \sa setCaCertificates()

   493 */

   494 QList<QSslCertificate> QSslConfiguration::caCertificates() const

   495 {

   496     return d ? d->caCertificates : QList<QSslCertificate>();

   497 }

   498 

   499 /*!

   500   Sets this socket's CA certificate database to be \a certificates.

   501   The certificate database must be set prior to the SSL handshake.

   502   The CA certificate database is used by the socket during the

   503   handshake phase to validate the peer's certificate.

   504 

   505   \sa caCertificates()

   506 */

   507 void QSslConfiguration::setCaCertificates(const QList<QSslCertificate> &certificates)

   508 {

   509     d->caCertificates = certificates;

   510 }

   511 

   512 /*!

   513     Returns the default SSL configuration to be used in new SSL

   514     connections.

   515 

   516     The default SSL configuration consists of:

   517 

   518     \list

   519       \o no local certificate and no private key

   520       \o protocol SSLv3

   521       \o the system's default CA certificate list

   522       \o the cipher list equal to the list of the SSL libraries'

   523          supported SSL ciphers

   524     \endlist

   525 

   526     \sa QSslSocket::supportedCiphers(), setDefaultConfiguration()

   527 */

   528 QSslConfiguration QSslConfiguration::defaultConfiguration()

   529 {

   530     return QSslConfigurationPrivate::defaultConfiguration();

   531 }

   532 

   533 /*!

   534     Sets the default SSL configuration to be used in new SSL

   535     connections to be \a configuration. Existing connections are not

   536     affected by this call.

   537 

   538     \sa QSslSocket::supportedCiphers(), defaultConfiguration()

   539 */

   540 void QSslConfiguration::setDefaultConfiguration(const QSslConfiguration &configuration)

   541 {

   542     QSslConfigurationPrivate::setDefaultConfiguration(configuration);

   543 }

   544 

   545 QT_END_NAMESPACE