Home · All Classes · Main Classes · Grouped Classes · Modules · Functions

QSslSocket Class Reference
[QtNetwork module]

The QSslSocket class provides an SSL encrypted socket for both clients and servers. More...

 #include <QSslSocket>

Inherits QTcpSocket.

Note: All the functions in this class are reentrant.

This class was introduced in Qt 4.3.

Public Types

Public Functions

Public Slots

Signals

Static Public Members

Additional Inherited Members


Detailed Description

The QSslSocket class provides an SSL encrypted socket for both clients and servers.

QSslSocket establishes a secure, encrypted TCP connection that you can use for transmitting encrypted data. It can operate both in client and server mode, and it supports all modern SSL protocols, including SSLv3 and TLSv1. By default, QSslSocket uses SSLv3, but you can decide which SSL protocol to use by passing the protocol to QSslSocket's constructor.

SSL encryption operates on top of the existing TCP stream, and is entered after the socket enters ConnectedState. There are two main ways to establish a secure connection with QSslSocket: either with an immediate SSL handshake, or a delayed handshake where the socket starts out in plain, unencrypted mode, and later enters SSL mode.

The most common way to use QSslSocket is to construct an object, and start a connection by calling connectToHostEncrypted(), which starts an immediate SSL handshake once the connection has been established. As with a plain QTcpSocket, QSslSocket will enter HostLookupState, ConnectingState, and then ConnectedState if the connection has been successfully established. The hand shake will then start automatically, and if there are no problems, QSslSocket will emit encrypted(), indicating that the socket has entered its encrypted state, and is ready for use.

If an error occurs, QSslSocket will emit sslErrors(). Unless any action is taken, the connection will then be dropped; the connection will fail. To recover from an SSL handshake error, you must connect a slot to the sslErrors() signal, and call ignoreSslErrors() from within your slot. This will allow QSslSocket to ignore the errors it encountered when establishing the identity of the peer. This feature must be used with caution, as it's a fundamental property of a secure connection to have successfully completed the handshake phase.

Once encrypted, you can use QSslSocket just like a regular QTcpSocket. When readyRead() is emitted, you can call read(), canReadLin()/readLine() or getChar() to read decrypted data from QSslSocket's internal buffer, and you can call write() or putChar() to write data back to the peer. QSslSocket will automatically encrypt the data for you, and emit bytesWritten() once the data has been written to the peer.

As a convenience, QSslSocket also supports QTcpSocket's blocking functions waitForConnected(), waitForReadyRead(), waitForBytesWritten(), and waitForDisconnected(). In addition, it provides waitForEncrypted(), which will block the calling thread until an encrypted connection has been established.

QSslSocket provides an extensive, easy-to-use API for handling SSL certificates, ciphers, and for managing errors. You can customize the socket's cryptographic cipher suite and CA database by calling setCiphers() or setCaCertificates(). For more information about ciphers, refer to QSslCipher's documentation. You can read about SSL certificates in the class documentation for QSslCertificate.

This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/).

See also QSslCertificate, QSslCipher, and QSslError.


Member Type Documentation

enum QSslSocket::Mode

Describes the different connection modes a QSslSocket can be in.

ConstantValueDescription
QSslSocket::PlainMode0The socket is unencrypted, and behaves identically to QTcpSocket.
QSslSocket::SslClientMode1The socket is a client-side SSL socket, and is either encrypted, or in the handshake phase (see QSslSocket::isEncrypted()).
QSslSocket::SslServerMode2The socket is a client-side SSL socket, and is either encrypted, or in the handshake phase (see QSslSocket::isEncrypted()).

enum QSslSocket::Protocol

Describes the protocol to use for the connection.

ConstantValueDescription
QSslSocket::SslV30SSLv3
QSslSocket::SslV21SSLv2
QSslSocket::TlsV12TLSv1
QSslSocket::Compat3The socket understands SSLv2, SSLv3 and TLSv1.


Member Function Documentation

QSslSocket::QSslSocket ( QObject * parent = 0 )

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

QSslSocket::~QSslSocket ()

Destroys the QSslSocket.

void QSslSocket::addCaCertificate ( const QSslCertificate & certificate )

Adds certificate to this socket's CA certificate database.

See also caCertificates(), resetCaCertificates(), and addGlobalCaCertificate().

bool QSslSocket::addCaCertificates ( const QString & path )

Adds all CA certificates in path, which may be a file, or a directory with wildcards. Returns true on success; otherwise returns false.

For more fine grained control, you can call addCaCertificate() instead.

See also addCaCertificate().

void QSslSocket::addCaCertificates ( const QList<QSslCertificate> & certificates )

This is an overloaded member function, provided for convenience.

Adds certificates to this socket's CA certificate database.

See also caCertificates(), resetCaCertificates(), and addGlobalCaCertificate().

void QSslSocket::addGlobalCaCertificate ( const QSslCertificate & certificate )   [static]

Adds certificate to the global CA certificate database.

See also globalCaCertificates() and addCaCertificates().

bool QSslSocket::addGlobalCaCertificates ( const QString & path )   [static]

Adds all CA certificates in path to the global CA certificate database. path can be a file, or a directory with wildcards. Returns true on success; otherwise returns false.

See also globalCaCertificates(), addCaCertificates(), and addGlobalCaCertificate().

void QSslSocket::addGlobalCaCertificates ( const QList<QSslCertificate> & certificates )   [static]

This is an overloaded member function, provided for convenience.

Adds certificates to the global CA certificate database.

See also globalCaCertificates() and addCaCertificates().

QList<QSslCertificate> QSslSocket::caCertificates () const

Returns this socket's CA certificate database.

See also setCaCertificates(), addCaCertificates(), and globalCaCertificates().

QList<QSslCipher> QSslSocket::ciphers () const

Returns this socket's current cryptographic cipher suite. This list is used during the socket's handshake phase when negotiating ciphers with the peer. The list is returned in descending preferred order (i.e., the first cipher in the list is the most preferred cipher).

By default, the socket will use a predefined set of ciphers that works for most common cases. This predefined set is defined by the current SSL libraries, and may vary from system to system.

See also setCiphers(), resetCiphers(), globalCiphers(), and supportedCiphers().

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

Starts an encrypted connection to hostName on port, using mode as the device OpenMode. This is equivalent to calling connectToHost(), and then calling startClientHandShake() after the connection has been established.

QSslSocket will enter HostLookupState, and after entering the event loop (or calling one of the waitFor...() functions), it will enter ConnectingState, emit connected(), and then start the SSL client handshake. Between all state changes, QSslSocket emits stateChanged().

After initiating the SSL client handshake, QSslSocket can emit sslErrors(), indicating that the identity of the peer could not be established. If you want to ignore the errors and continue connecting, you must call ignoreSslErrors() from inside a slot connected to the sslErrors() signal. Otherwise, the connection will be dropped (QSslSocket emits disconnected(), and reenters UnconnectedState).

If the SSL handshake is completed successfully, QSslSocket will emit encrypted().

 QSslSocket socket;
 connect(&socket, SIGNAL(encrypted()), receiver, SLOT(socketEncrypted()));

 socket.connectToHostEncrypted("imap", 993);

The default for mode is ReadWrite.

If you want to create a QSslSocket on the server side of a connection, you should instead call startServerHandShake() upon receiving the incoming connection through QTcpServer.

See also connectToHost(), startClientHandShake(), waitForConnected(), and waitForEncrypted().

QSslCipher QSslSocket::currentCipher () const

Returns the socket's current cryptographic cipher, or a null cipher if the connection isn't encrypted. You can call this function to find information about the cipher that is used to encrypt and decrypt all data transmitted through this socket.

QSslSocket also provides functions for selecting which ciphers should be used for encrypting data.

See also ciphers(), resetCiphers(), setCiphers(), setGlobalCiphers(), resetGlobalCiphers(), globalCiphers(), and supportedCiphers().

void QSslSocket::encrypted ()   [signal]

This signal is emitted when QSslSocket enters encrypted mode. After this signal has been emitted, QSslSocket::isEncrypted() will return true, and all further transmissions on the socket will be encrypted.

See also QSslSocket::connectToHostEncrypted() and QSslSocket::isEncrypted().

QList<QSslCertificate> QSslSocket::globalCaCertificates ()   [static]

Returns the global CA certificate database.

See also setGlobalCaCertificates() and caCertificates().

QList<QSslCipher> QSslSocket::globalCiphers ()   [static]

Returns the default cryptographic cipher suite for all sockets in this application. This list is used during the socket's handshake phase when negotiating ciphers with the peer. The list is returned in descending preferred order (i.e., the first cipher in the list is the most preferred cipher).

By default, the system will use a predefined set of ciphers that works for most common cases. This set is defined by the current SSL libraries, and may vary from system to system.

See also setGlobalCiphers() and supportedCiphers().

void QSslSocket::ignoreSslErrors ()   [slot]

This slot allows QSslSocket to ignore all errors during QSslSocket's handshake phase, and continue connecting. If the handshake fails with one or more errors, you must call this function from a slot connected to sslErrors() to continue the connection; otherwise, the connection will be dropped immediately after the signal has been emitted.

If there are no errors during the SSL handshake phase (i.e., the identity of the peer is established with no problems), QSslSocket will not emit the sslErrors() signal, and it is unnecessary to call this function.

See also sslErrors().

bool QSslSocket::isEncrypted () const

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

An encrypted socket encrypts all data that is written by calling write() or putChar() before the data is written to the network, and descrypts all incoming data as the data is received from the network, before you call read(), readLine() or getChar().

QSslSocket emits encrypted() when it enters encrypted mode.

You can call currentCipher() to find which cryptographic cipher is used to encrypt and decrypt your data.

See also mode().

QSslCertificate QSslSocket::localCertificate () const

Returns the socket's local certificate, or an empty certificate if no local certificate has been assigned.

See also setLocalCertificate() and privateKey().

Mode QSslSocket::mode () const

Returns the current mode for the socket; either PlainMode, where QSslSocket behaves identially to QTcpSocket, or one of SslClientMode or SslServerMode, where the client is either negotiating or in encrypted mode.

When the mode changes, QSslSocket emits modeChanged()

See also Mode.

void QSslSocket::modeChanged ( QSslSocket::Mode mode )   [signal]

This signal is emitted when QSslSocket changes from QSslSocket::PlainMode to either QSslSocket::SslClientMode or QSslSocket::SslServerMode. mode is the new mode.

See also QSslSocket::mode().

QSslCertificate QSslSocket::peerCertificate () const

Returns the peer's certificate (i.e., the immediate certificate of the host you are connected to), or a null certificate if either the peer hasn't provided any certificate (common for server sockets).

The peer certificate is provided for connection diagnostic purposes, and it's commonly used for displaying to the user. It contains information about the peer, including its host name, the certificate issuer, and the peer's public key.

The peer certificate is set during the handshake phase, so it's safe to check this certificate from inside a slot connected to the sslErrors() or encrypted() signals.

If you also want to check the rest of the peer's chain of certificates, you can call peerCertificateChain().

See also peerCertificateChain().

QList<QSslCertificate> QSslSocket::peerCertificateChain () const

Returns the peer's chain of certificates, or an empty list of certificates if the peer either hasn't provided any certificates.

The peer certificate chain is provided for connection diagnostic purposes, and it's commonly used for displaying to the user. It contains information about the peer, including its host name, the certificate issuer and its chain of authorities, and the peer's and issuer's public keys.

The peer certificates are set during the handshake phase, so it's safe to check the certificate chain from inside a slot connected to the sslErrors() or encrypted() signals.

If all you want is to check the peer's own certificate, you can call peerCertificateChain() instead.

See also peerCertificate().

QSslKey QSslSocket::privateKey () const

Returns this socket's private key.

See also setPrivateKey() and localCertificate().

Protocol QSslSocket::protocol () const

Returns the socket's SSL protocol. By default, SslV3 is used.

ConstantValue
QSslSocket::setProtocol() 

See also setProtocol().

void QSslSocket::resetCaCertificates ()

Resets this socket's CA certificate database. The socket will fall back to using the global CA certificate database (See globalCaCertificates()).

See also addCaCertificate() and setGlobalCaCertificates().

void QSslSocket::resetCiphers ()

Resets this socket's cryptographic cipher suite back to the global default. This is the same as calling setCiphers(globalCiphers()).

See also ciphers(), setCiphers(), resetGlobalCiphers(), and supportedCiphers().

void QSslSocket::resetGlobalCiphers ()   [static]

Resets the default cryptographic cipher suite for all sockets in this application.

See also resetCiphers(), setGlobalCiphers(), globalCiphers(), and supportedCiphers().

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

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

See also caCertificates(), resetCaCertificates(), and addGlobalCaCertificate().

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

Sets the cryptographic cipher suite for this socket to ciphers.

See also ciphers(), setGlobalCiphers(), and supportedCiphers().

void QSslSocket::setGlobalCaCertificates ( const QList<QSslCertificate> & certificates )   [static]

Sets certificates to be QSslSocket's global CA certificate database.

See also globalCaCertificates(), resetCaCertificates(), and addGlobalCaCertificate().

void QSslSocket::setGlobalCiphers ( const QList<QSslCipher> & ciphers )   [static]

Sets the default cryptographic cipher suite for all sockets in this application to ciphers.

See also setCiphers(), resetGlobalCiphers(), globalCiphers(), and supportedCiphers().

void QSslSocket::setLocalCertificate ( const QSslCertificate & certificate )

Sets the socket's local certificate to certificate. The local certificate is necessary if you need to confirm your identity to the peer. It is used together with the private key; if you set the local certificate, you must also set the private key.

The local certificate and private key are always necessary for server sockets, but are also rarely used by client sockets if the server requires the client to authenticate.

See also localCertificate() and setPrivateKey().

void QSslSocket::setPrivateKey ( const QSslKey & key )

Sets the socket's private key to key. The private key and local certificate are used by clients or servers that need to prove their identity to the peer. This key and the local certificate are necessary for all SSL server sockets, but are rarely also used by clients that need to authenticate against a server.

See also privateKey() and setLocalCertificate().

void QSslSocket::setProtocol ( Protocol protocol )

Sets the socket's SSL protocol to protocol. This will affect the next initiated handshake; calling this function on an already-encrypted socket will not affect the socket's protocol.

ConstantValue
QSslSocket::setProtocol() 

See also protocol().

void QSslSocket::sslErrors ( const QList<QSslError> & errors )   [signal]

QSslSocket emits this signal during the SSL handshake to indicate that an error has occurred while establishing the identity of the peer. The error is usually an indication that QSslSocket is unable to securely identify the peer. Unless any action is taken, the connection will be dropped after this signal has been emitted.

If you want to continue connecting despite the errors that have occurred, you must call QSslSocket::ignoreErrors() from inside a slot connected to this signal.

errors contains one or more errors that prevent QSslSocket from verifying the identity of the peer.

Note: You cannot use Qt::QueuedConnection when connecting to this signal, or calling QSslSocket::ignoreErrors() will have no effect.

void QSslSocket::startClientHandShake ()   [slot]

Starts a delayed SSL handshake for a client connection. This function must be called when the socket is in PlainMode, and ConnectedState; otherwise, it has no effect.

Clients that implement STARTTLS functionality often make use of delayed SSL handshakes; most other clients can avoid calling this function directly by using connectToHostEncrypted() instead.

See also connectToHostEncrypted() and startServerHandShake().

void QSslSocket::startServerHandShake ()   [slot]

Starts a delayed SSL handshake for a server connection. This function must be called when the socket is in PlainMode, and ConnectedState; otherwise, it has no effect.

For server sockets, calling this function is the only way to initiate the SSL handshake. Most servers will call this function immediately upon receiving a connection, or as a result of having received a protocol-specific command to enter SSL mode (e.g, the server may respond to receiving the string "STARTTLS\r\n" by calling this function).

The most common way to implement SSL servers is to create a subclass of QTcpServer, and reimplement QTcpServer::incomingConnection(). The provided socket descriptor is then passed to QSslSocket::setSocketDescriptor().

See also connectToHostEncrypted() and startClientHandShake().

QList<QSslCipher> QSslSocket::supportedCiphers ()   [static]

Returns the list of cryptographic ciphers supported by this system.

This list is determined by the current SSL libraries, and may vary from system to system.

See also globalCiphers(), ciphers(), and setCiphers().

bool QSslSocket::supportsSsl ()   [static]

Returns true if this platform supports SSL; otherwise, returns false.

If the platform doesn't support SSL, the socket will fail in the connection phase.

QList<QSslCertificate> QSslSocket::systemCaCertificates ()   [static]

Returns the default CA certificate database for the system.

See also caCertificates().

bool QSslSocket::waitForEncrypted ( int msecs )

Waits until the socket has completed the SSL handshake and has emitted encrypted(), up to msecs milliseconds. If encrypted() has been emitted, this function returns true; otherwise (e.g., the socket is disconnected, or the SSL handshake fails), false is returned.

The following example waits up to one second for the socket to be encrypted:

 socket->connectToHostEncrypted("imap", 993);
 if (socket->waitForEncrypted(1000))
     qDebug("Encrypted!");

If msecs is -1, this function will not time out.

See also startClientHandShake(), startServerHandShake(), encrypted(), and isEncrypted().


Copyright © 2007 Trolltech Trademarks
Qt 4.3.0beta