src/network/ssl/qsslconfiguration.cpp

   1 /****************************************************************************
   2 **
   3 ** Copyright (C) 2012 Nokia Corporation and/or its subsidiary(-ies).
   4 ** Contact: http://www.qt-project.org/
   5 **
   6 ** This file is part of the QtNetwork module of the Qt Toolkit.
   7 **
   8 ** $QT_BEGIN_LICENSE:LGPL$
   9 ** GNU Lesser General Public License Usage
  10 ** This file may be used under the terms of the GNU Lesser General Public
  11 ** License version 2.1 as published by the Free Software Foundation and
  12 ** appearing in the file LICENSE.LGPL included in the packaging of this
  13 ** file. Please review the following information to ensure the GNU Lesser
  14 ** General Public License version 2.1 requirements will be met:
  15 ** http://www.gnu.org/licenses/old-licenses/lgpl-2.1.html.
  16 **
  17 ** In addition, as a special exception, Nokia gives you certain additional
  18 ** rights. These rights are described in the Nokia Qt LGPL Exception
  19 ** version 1.1, included in the file LGPL_EXCEPTION.txt in this package.
  20 **
  21 ** GNU General Public License Usage
  22 ** Alternatively, this file may be used under the terms of the GNU General
  23 ** Public License version 3.0 as published by the Free Software Foundation
  24 ** and appearing in the file LICENSE.GPL included in the packaging of this
  25 ** file. Please review the following information to ensure the GNU General
  26 ** Public License version 3.0 requirements will be met:
  27 ** http://www.gnu.org/copyleft/gpl.html.
  28 **
  29 ** Other Usage
  30 ** Alternatively, this file may be used in accordance with the terms and
  31 ** conditions contained in a signed written agreement between you and Nokia.
  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 const QSsl::SslOptions QSslConfigurationPrivate::defaultSslOptions = QSsl::SslOptionDisableEmptyFragments
  51                                                                     |QSsl::SslOptionDisableLegacyRenegotiation;
  52
  53 /*!
  54     \class QSslConfiguration
  55     \brief The QSslConfiguration class holds the configuration and state of an SSL connection
  56     \since 4.4
  57
  58     \reentrant
  59     \inmodule QtNetwork
  60     \ingroup network
  61     \ingroup ssl
  62
  63     QSslConfiguration is used by Qt networking classes to relay
  64     information about an open SSL connection and to allow the
  65     application to control certain features of that connection.
  66
  67     The settings that QSslConfiguration currently supports are:
  68
  69     \list
  70       \li The SSL/TLS protocol to be used
  71       \li The certificate to be presented to the peer during connection
  72          and its associated private key
  73       \li The ciphers allowed to be used for encrypting the connection
  74       \li The list of Certificate Authorities certificates that are
  75          used to validate the peer's certificate
  76     \endlist
  77
  78     These settings are applied only during the connection
  79     handshake. Setting them after the connection has been established
  80     has no effect.
  81
  82     The state that QSslConfiguration supports are:
  83     \list
  84       \li The certificate the peer presented during handshake, along
  85          with the chain leading to a CA certificate
  86       \li The cipher used to encrypt this session
  87     \endlist
  88
  89     The state can only be obtained once the SSL connection starts, but
  90     not necessarily before it's done. Some settings may change during
  91     the course of the SSL connection without need to restart it (for
  92     instance, the cipher can be changed over time).
  93
  94     State in QSslConfiguration objects cannot be changed.
  95
  96     QSslConfiguration can be used with QSslSocket and the Network
  97     Access API.
  98
  99     Note that changing settings in QSslConfiguration is not enough to
 100     change the settings in the related SSL connection. You must call
 101     setSslConfiguration on a modified QSslConfiguration object to
 102     achieve that. The following example illustrates how to change the
 103     protocol to TLSv1_0 in a QSslSocket object:
 104
 105     \snippet code/src_network_ssl_qsslconfiguration.cpp 0
 106
 107     \sa QSsl::SslProtocol, QSslCertificate, QSslCipher, QSslKey
 108         QSslSocket, QNetworkAccessManager,
 109         QSslSocket::sslConfiguration(), QSslSocket::setSslConfiguration()
 110 */
 111
 112 /*!
 113     Constructs an empty SSL configuration. This configuration contains
 114     no valid settings and the state will be empty. isNull() will
 115     return true after this constructor is called.
 116
 117     Once any setter methods are called, isNull() will return false.
 118 */
 119 QSslConfiguration::QSslConfiguration()
 120     : d(new QSslConfigurationPrivate)
 121 {
 122 }
 123
 124 /*!
 125     Copies the configuration and state of \a other. If \a other is
 126     null, this object will be null too.
 127 */
 128 QSslConfiguration::QSslConfiguration(const QSslConfiguration &other)
 129     : d(other.d)
 130 {
 131 }
 132
 133 /*!
 134     Releases any resources held by QSslConfiguration.
 135 */
 136 QSslConfiguration::~QSslConfiguration()
 137 {
 138     // QSharedDataPointer deletes d for us if necessary
 139 }
 140
 141 /*!
 142     Copies the configuration and state of \a other. If \a other is
 143     null, this object will be null too.
 144 */
 145 QSslConfiguration &QSslConfiguration::operator=(const QSslConfiguration &other)
 146 {
 147     d = other.d;
 148     return *this;
 149 }
 150
 151 /*!
 152     Returns true if this QSslConfiguration object is equal to \a
 153     other.
 154
 155     Two QSslConfiguration objects are considered equal if they have
 156     the exact same settings and state.
 157
 158     \sa operator!=()
 159 */
 160 bool QSslConfiguration::operator==(const QSslConfiguration &other) const
 161 {
 162     if (d == other.d)
 163         return true;
 164     return d->peerCertificate == other.d->peerCertificate &&
 165         d->peerCertificateChain == other.d->peerCertificateChain &&
 166         d->localCertificate == other.d->localCertificate &&
 167         d->privateKey == other.d->privateKey &&
 168         d->sessionCipher == other.d->sessionCipher &&
 169         d->ciphers == other.d->ciphers &&
 170         d->caCertificates == other.d->caCertificates &&
 171         d->protocol == other.d->protocol &&
 172         d->peerVerifyMode == other.d->peerVerifyMode &&
 173         d->peerVerifyDepth == other.d->peerVerifyDepth &&
 174         d->sslOptions == other.d->sslOptions;
 175 }
 176
 177 /*!
 178     \fn QSslConfiguration::operator!=(const QSslConfiguration &other) const
 179
 180     Returns true if this QSslConfiguration differs from \a other. Two
 181     QSslConfiguration objects are considered different if any state or
 182     setting is different.
 183
 184     \sa operator==()
 185 */
 186
 187 /*!
 188     Returns true if this is a null QSslConfiguration object.
 189
 190     A QSslConfiguration object is null if it has been
 191     default-constructed and no setter methods have been called.
 192
 193     \sa setProtocol(), setLocalCertificate(), setPrivateKey(),
 194         setCiphers(), setCaCertificates()
 195 */
 196 bool QSslConfiguration::isNull() const
 197 {
 198     return (d->protocol == QSsl::SecureProtocols &&
 199             d->peerVerifyMode == QSslSocket::AutoVerifyPeer &&
 200             d->peerVerifyDepth == 0 &&
 201             d->caCertificates.count() == 0 &&
 202             d->ciphers.count() == 0 &&
 203             d->localCertificate.isNull() &&
 204             d->privateKey.isNull() &&
 205             d->peerCertificate.isNull() &&
 206             d->peerCertificateChain.count() == 0 &&
 207             d->sslOptions == QSslConfigurationPrivate::defaultSslOptions);
 208 }
 209
 210 /*!
 211     Returns the protocol setting for this SSL configuration.
 212
 213     \sa setProtocol()
 214 */
 215 QSsl::SslProtocol QSslConfiguration::protocol() const
 216 {
 217     return d->protocol;
 218 }
 219
 220 /*!
 221     Sets the protocol setting for this configuration to be \a
 222     protocol.
 223
 224     Setting the protocol once the connection has already been
 225     established has no effect.
 226
 227     \sa protocol()
 228 */
 229 void QSslConfiguration::setProtocol(QSsl::SslProtocol protocol)
 230 {
 231     d->protocol = protocol;
 232 }
 233
 234 /*!
 235     Returns the verify mode. This mode decides whether QSslSocket should
 236     request a certificate from the peer (i.e., the client requests a
 237     certificate from the server, or a server requesting a certificate from the
 238     client), and whether it should require that this certificate is valid.
 239
 240     The default mode is AutoVerifyPeer, which tells QSslSocket to use
 241     VerifyPeer for clients, QueryPeer for servers.
 242
 243     \sa setPeerVerifyMode()
 244 */
 245 QSslSocket::PeerVerifyMode QSslConfiguration::peerVerifyMode() const
 246 {
 247     return d->peerVerifyMode;
 248 }
 249
 250 /*!
 251     Sets the verify mode to \a mode. This mode decides whether QSslSocket
 252     should request a certificate from the peer (i.e., the client requests a
 253     certificate from the server, or a server requesting a certificate from the
 254     client), and whether it should require that this certificate is valid.
 255
 256     The default mode is AutoVerifyPeer, which tells QSslSocket to use
 257     VerifyPeer for clients, QueryPeer for servers.
 258
 259     \sa peerVerifyMode()
 260 */
 261 void QSslConfiguration::setPeerVerifyMode(QSslSocket::PeerVerifyMode mode)
 262 {
 263     d->peerVerifyMode = mode;
 264 }
 265
 266
 267 /*!
 268     Returns the maximum number of certificates in the peer's certificate chain
 269     to be checked during the SSL handshake phase, or 0 (the default) if no
 270     maximum depth has been set, indicating that the whole certificate chain
 271     should be checked.
 272
 273     The certificates are checked in issuing order, starting with the peer's
 274     own certificate, then its issuer's certificate, and so on.
 275
 276     \sa setPeerVerifyDepth(), peerVerifyMode()
 277 */
 278 int QSslConfiguration::peerVerifyDepth() const
 279 {
 280     return d->peerVerifyDepth;
 281 }
 282
 283 /*!
 284     Sets the maximum number of certificates in the peer's certificate chain to
 285     be checked during the SSL handshake phase, to \a depth. Setting a depth of
 286     0 means that no maximum depth is set, indicating that the whole
 287     certificate chain should be checked.
 288
 289     The certificates are checked in issuing order, starting with the peer's
 290     own certificate, then its issuer's certificate, and so on.
 291
 292     \sa peerVerifyDepth(), setPeerVerifyMode()
 293 */
 294 void QSslConfiguration::setPeerVerifyDepth(int depth)
 295 {
 296     if (depth < 0) {
 297         qWarning("QSslConfiguration::setPeerVerifyDepth: cannot set negative depth of %d", depth);
 298         return;
 299     }
 300     d->peerVerifyDepth = depth;
 301 }
 302
 303 /*!
 304     Returns the certificate to be presented to the peer during the SSL
 305     handshake process.
 306
 307     \sa setLocalCertificate()
 308 */
 309 QSslCertificate QSslConfiguration::localCertificate() const
 310 {
 311     return d->localCertificate;
 312 }
 313
 314 /*!
 315     Sets the certificate to be presented to the peer during SSL
 316     handshake to be \a certificate.
 317
 318     Setting the certificate once the connection has been established
 319     has no effect.
 320
 321     A certificate is the means of identification used in the SSL
 322     process. The local certificate is used by the remote end to verify
 323     the local user's identity against its list of Certification
 324     Authorities. In most cases, such as in HTTP web browsing, only
 325     servers identify to the clients, so the client does not send a
 326     certificate.
 327
 328     \sa localCertificate()
 329 */
 330 void QSslConfiguration::setLocalCertificate(const QSslCertificate &certificate)
 331 {
 332     d->localCertificate = certificate;
 333 }
 334
 335 /*!
 336     Returns the peer's digital certificate (i.e., the immediate
 337     certificate of the host you are connected to), or a null
 338     certificate, if the peer has not assigned a certificate.
 339
 340     The peer certificate is checked automatically during the
 341     handshake phase, so this function is normally used to fetch
 342     the certificate for display or for connection diagnostic
 343     purposes. It contains information about the peer, including
 344     its host name, the certificate issuer, and the peer's public
 345     key.
 346
 347     Because the peer certificate is set during the handshake phase, it
 348     is safe to access the peer certificate from a slot connected to
 349     the QSslSocket::sslErrors() signal, QNetworkReply::sslErrors()
 350     signal, or the QSslSocket::encrypted() signal.
 351
 352     If a null certificate is returned, it can mean the SSL handshake
 353     failed, or it can mean the host you are connected to doesn't have
 354     a certificate, or it can mean there is no connection.
 355
 356     If you want to check the peer's complete chain of certificates,
 357     use peerCertificateChain() to get them all at once.
 358
 359     \sa peerCertificateChain(),
 360         QSslSocket::sslErrors(), QSslSocket::ignoreSslErrors(),
 361         QNetworkReply::sslErrors(), QNetworkReply::ignoreSslErrors()
 362 */
 363 QSslCertificate QSslConfiguration::peerCertificate() const
 364 {
 365     return d->peerCertificate;
 366 }
 367
 368 /*!
 369     Returns the peer's chain of digital certificates, starting with
 370     the peer's immediate certificate and ending with the CA's
 371     certificate.
 372
 373     Peer certificates are checked automatically during the handshake
 374     phase. This function is normally used to fetch certificates for
 375     display, or for performing connection diagnostics. Certificates
 376     contain information about the peer and the certificate issuers,
 377     including host name, issuer names, and issuer public keys.
 378
 379     Because the peer certificate is set during the handshake phase, it
 380     is safe to access the peer certificate from a slot connected to
 381     the QSslSocket::sslErrors() signal, QNetworkReply::sslErrors()
 382     signal, or the QSslSocket::encrypted() signal.
 383
 384     If an empty list is returned, it can mean the SSL handshake
 385     failed, or it can mean the host you are connected to doesn't have
 386     a certificate, or it can mean there is no connection.
 387
 388     If you want to get only the peer's immediate certificate, use
 389     peerCertificate().
 390
 391     \sa peerCertificate(),
 392         QSslSocket::sslErrors(), QSslSocket::ignoreSslErrors(),
 393         QNetworkReply::sslErrors(), QNetworkReply::ignoreSslErrors()
 394 */
 395 QList<QSslCertificate> QSslConfiguration::peerCertificateChain() const
 396 {
 397     return d->peerCertificateChain;
 398 }
 399
 400 /*!
 401     Returns the socket's cryptographic \l {QSslCipher} {cipher}, or a
 402     null cipher if the connection isn't encrypted. The socket's cipher
 403     for the session is set during the handshake phase. The cipher is
 404     used to encrypt and decrypt data transmitted through the socket.
 405
 406     The SSL infrastructure also provides functions for setting the
 407     ordered list of ciphers from which the handshake phase will
 408     eventually select the session cipher. This ordered list must be in
 409     place before the handshake phase begins.
 410
 411     \sa ciphers(), setCiphers(), QSslSocket::supportedCiphers()
 412 */
 413 QSslCipher QSslConfiguration::sessionCipher() const
 414 {
 415     return d->sessionCipher;
 416 }
 417
 418 /*!
 419     Returns the \l {QSslKey} {SSL key} assigned to this connection or
 420     a null key if none has been assigned yet.
 421
 422     \sa setPrivateKey(), localCertificate()
 423 */
 424 QSslKey QSslConfiguration::privateKey() const
 425 {
 426     return d->privateKey;
 427 }
 428
 429 /*!
 430     Sets the connection's private \l {QSslKey} {key} to \a key. The
 431     private key and the local \l {QSslCertificate} {certificate} are
 432     used by clients and servers that must prove their identity to
 433     SSL peers.
 434
 435     Both the key and the local certificate are required if you are
 436     creating an SSL server socket. If you are creating an SSL client
 437     socket, the key and local certificate are required if your client
 438     must identify itself to an SSL server.
 439
 440     \sa privateKey(), setLocalCertificate()
 441 */
 442 void QSslConfiguration::setPrivateKey(const QSslKey &key)
 443 {
 444     d->privateKey = key;
 445 }
 446
 447 /*!
 448     Returns this connection's current cryptographic cipher suite. This
 449     list is used during the handshake phase for choosing a
 450     session cipher. The returned list of ciphers is ordered by
 451     descending preference. (i.e., the first cipher in the list is the
 452     most preferred cipher). The session cipher will be the first one
 453     in the list that is also supported by the peer.
 454
 455     By default, the handshake phase can choose any of the ciphers
 456     supported by this system's SSL libraries, which may vary from
 457     system to system. The list of ciphers supported by this system's
 458     SSL libraries is returned by QSslSocket::supportedCiphers(). You can restrict
 459     the list of ciphers used for choosing the session cipher for this
 460     socket by calling setCiphers() with a subset of the supported
 461     ciphers. You can revert to using the entire set by calling
 462     setCiphers() with the list returned by QSslSocket::supportedCiphers().
 463
 464     \sa setCiphers(), QSslSocket::supportedCiphers()
 465 */
 466 QList<QSslCipher> QSslConfiguration::ciphers() const
 467 {
 468     return d->ciphers;
 469 }
 470
 471 /*!
 472     Sets the cryptographic cipher suite for this socket to \a ciphers,
 473     which must contain a subset of the ciphers in the list returned by
 474     supportedCiphers().
 475
 476     Restricting the cipher suite must be done before the handshake
 477     phase, where the session cipher is chosen.
 478
 479     \sa ciphers(), QSslSocket::supportedCiphers()
 480 */
 481 void QSslConfiguration::setCiphers(const QList<QSslCipher> &ciphers)
 482 {
 483     d->ciphers = ciphers;
 484 }
 485
 486 /*!
 487   Returns this connection's CA certificate database. The CA certificate
 488   database is used by the socket during the handshake phase to
 489   validate the peer's certificate. It can be modified prior to the
 490   handshake with setCaCertificates(), or with \l{QSslSocket}'s
 491   \l{QSslSocket::}{addCaCertificate()} and
 492   \l{QSslSocket::}{addCaCertificates()}.
 493
 494   \sa setCaCertificates()
 495 */
 496 QList<QSslCertificate> QSslConfiguration::caCertificates() const
 497 {
 498     return d->caCertificates;
 499 }
 500
 501 /*!
 502   Sets this socket's CA certificate database to be \a certificates.
 503   The certificate database must be set prior to the SSL handshake.
 504   The CA certificate database is used by the socket during the
 505   handshake phase to validate the peer's certificate.
 506
 507   \sa caCertificates()
 508 */
 509 void QSslConfiguration::setCaCertificates(const QList<QSslCertificate> &certificates)
 510 {
 511     d->caCertificates = certificates;
 512 }
 513
 514 /*!
 515   Enables or disables an SSL compatibility option.
 516
 517   \sa testSSlOption()
 518 */
 519 void QSslConfiguration::setSslOption(QSsl::SslOption option, bool on)
 520 {
 521     if (on)
 522         d->sslOptions |= option;
 523     else
 524         d->sslOptions &= ~option;
 525 }
 526
 527 /*!
 528   Returns true if the specified SSL compatibility option is enabled.
 529
 530   \sa testSSlOption()
 531 */
 532 bool QSslConfiguration::testSslOption(QSsl::SslOption option) const
 533 {
 534     return d->sslOptions & option;
 535 }
 536
 537 /*!
 538     Returns the default SSL configuration to be used in new SSL
 539     connections.
 540
 541     The default SSL configuration consists of:
 542
 543     \list
 544       \li no local certificate and no private key
 545       \li protocol SecureProtocols (meaning either TLS 1.0 or SSL 3 will be used)
 546       \li the system's default CA certificate list
 547       \li the cipher list equal to the list of the SSL libraries'
 548          supported SSL ciphers
 549     \endlist
 550
 551     \sa QSslSocket::supportedCiphers(), setDefaultConfiguration()
 552 */
 553 QSslConfiguration QSslConfiguration::defaultConfiguration()
 554 {
 555     return QSslConfigurationPrivate::defaultConfiguration();
 556 }
 557
 558 /*!
 559     Sets the default SSL configuration to be used in new SSL
 560     connections to be \a configuration. Existing connections are not
 561     affected by this call.
 562
 563     \sa QSslSocket::supportedCiphers(), defaultConfiguration()
 564 */
 565 void QSslConfiguration::setDefaultConfiguration(const QSslConfiguration &configuration)
 566 {
 567     QSslConfigurationPrivate::setDefaultConfiguration(configuration);
 568 }
 569
 570 QT_END_NAMESPACE