QSslSocket Class

The QSslSocket class provides an encrypted TCP connection using TLS. More…

List of all members, including inherited members

Public Types

Public Functions

Reimplemented Public Functions

Public Slots

Signals

Static Public Members

Reimplemented Protected Functions

Detailed Description

QSslSocket is a QTcpSocket that encrypts what you write and decrypts what you read. Use it like any other socket, starting when encrypted() is emitted:

QSslSocket socket;
QObject::connect(&socket, &QSslSocket::encrypted, [&] {
    socket.write("GET / HTTP/1.1\r\nHost: example.com\r\n\r\n");
});
QObject::connect(&socket, &QIODevice::readyRead, [&] {
    qDebug() << socket.readAll();
});
socket.connectToHostEncrypted("example.com", 443);

Clients verify the server by default: the certificate must chain to a trusted CA and match the host name. On failure sslErrors() is emitted and the connection closes, with nothing sent. A slot can call ignoreSslErrors() to continue, which removes the protection TLS gives against impersonation, so pass the specific errors you expect, not none at all.

To encrypt an existing connection, as with STARTTLS, call startClientEncryption() once connected.

Servers need a certificate and key; see QSslServer.

See also QSslConfiguration, QSslServer and QSslCertificate.

Differences from Qt

Member Type Documentation

enum QSslSocket::PeerVerifyMode

Selects how the peer's certificate is treated.

enum QSslSocket::SslMode

Describes what the socket is doing.

Member Function Documentation

[explicit] QSslSocket::QSslSocket(QObject *parent = nullptr)

Constructs a socket with the given parent.

[override] QSslSocket::~QSslSocket()

Destroys the socket.

[override] qint64 QSslSocket::bytesToWrite() const

Reimplements QTcpSocket::bytesToWrite().

[override] void QSslSocket::close()

Reimplements QTcpSocket::close().

[override, protected] void QSslSocket::connectionLost(int error)

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

Connects to hostName on port with the open mode mode, using the network protocol protocol, then starts a TLS handshake. The host name is also the name the certificate must match.

See also encrypted() and setPeerVerifyName().

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

This is an overloaded function.

Connects to hostName on port as above, and checks the certificate against sslPeerName, using the open mode mode and network protocol protocol.

[override] void QSslSocket::disconnectFromHost()

Reimplements QTcpSocket::disconnectFromHost().

[signal] void QSslSocket::encrypted()

This signal is emitted when the handshake has finished and the peer has been verified. Data can flow from this point.

See also isEncrypted().

qint64 QSslSocket::encryptedBytesAvailable() const

Returns the number of encrypted bytes waiting to be decrypted. Nt decrypts data as it arrives, so this is always 0.

qint64 QSslSocket::encryptedBytesToWrite() const

Returns the number of encrypted bytes waiting to reach the operating system.

[signal] void QSslSocket::encryptedBytesWritten(qint64 totalBytes)

This signal is emitted when totalBytes of encrypted data have reached the operating system.

void QSslSocket::ignoreSslErrors(const QList<QSslError> &errors)

Continues the connection despite the errors listed, and no others. Call this before connecting, or from a slot connected to sslErrors().

See also sslErrors().

[slot] void QSslSocket::ignoreSslErrors()

This is an overloaded function.

Continues the connection despite every verification problem. Call this from a slot connected to sslErrors(), after looking at the errors. It removes the protection TLS gives against impersonation.

bool QSslSocket::isEncrypted() const

Returns true once the handshake has finished and the peer has been verified.

See also encrypted().

QSslCertificate QSslSocket::localCertificate() const

Returns the certificate this side presents.

See also setLocalCertificate().

SslMode QSslSocket::mode() const

Returns the socket's mode.

See also modeChanged() and isEncrypted().

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

This signal is emitted when the mode changes to mode.

QSslCertificate QSslSocket::peerCertificate() const

Returns the peer's certificate, or a null certificate if it has not been received. It stays available after the connection closes.

See also peerCertificateChain().

QList<QSslCertificate> QSslSocket::peerCertificateChain() const

Returns the peer's certificate chain, leaf first.

See also peerCertificate().

int QSslSocket::peerVerifyDepth() const

Returns the longest certificate chain accepted; 0 means no limit.

See also setPeerVerifyDepth().

[signal] void QSslSocket::peerVerifyError(const QSslError &error)

This signal is emitted once per verification problem, with error, before sslErrors().

PeerVerifyMode QSslSocket::peerVerifyMode() const

Returns how the peer is verified.

See also setPeerVerifyMode().

QString QSslSocket::peerVerifyName() const

Returns the name the peer's certificate is checked against.

See also setPeerVerifyName().

QSslKey QSslSocket::privateKey() const

Returns the private key.

See also setPrivateKey().

QSsl::SslProtocol QSslSocket::protocol() const

Returns the allowed TLS versions.

See also setProtocol().

[override, protected] void QSslSocket::receivedRaw(const char *data, qint64 size)

[override, protected] void QSslSocket::remoteClosed()

QSslCipher QSslSocket::sessionCipher() const

Returns the cipher in use, or a null cipher before the handshake finishes.

QSsl::SslProtocol QSslSocket::sessionProtocol() const

Returns the TLS version in use, or UnknownProtocol before the handshake finishes.

void QSslSocket::setLocalCertificate(const QSslCertificate &certificate)

Sets the certificate this side presents to certificate.

See also localCertificate() and setPrivateKey().

void QSslSocket::setPeerVerifyDepth(int depth)

Sets the longest certificate chain accepted to depth.

See also peerVerifyDepth().

void QSslSocket::setPeerVerifyMode(PeerVerifyMode mode)

Sets how the peer is verified to mode. Using VerifyNone on a client removes the protection against impersonation.

See also peerVerifyMode().

void QSslSocket::setPeerVerifyName(const QString &hostName)

Sets the name the peer's certificate is checked against to hostName, for when it differs from the name connected to.

See also peerVerifyName().

void QSslSocket::setPrivateKey(const QSslKey &key)

Sets the private key of the local certificate to key.

See also privateKey().

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

Sets the allowed TLS versions to protocol, for the next handshake.

See also protocol().

void QSslSocket::setSslConfiguration(const QSslConfiguration &configuration)

Sets the configuration to configuration, for the next handshake.

See also sslConfiguration().

[override, protected] void QSslSocket::socketBytesWritten(qint64 size)

QSslConfiguration QSslSocket::sslConfiguration() const

Returns the configuration, including details of the session once the handshake has finished.

See also setSslConfiguration().

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

This signal is emitted after the handshake if verification found errors. Unless a connected slot calls ignoreSslErrors(), the connection is closed when this signal returns.

QList<QSslError> QSslSocket::sslHandshakeErrors() const

Returns the problems found during the last handshake.

See also sslErrors().

[static] long QSslSocket::sslLibraryBuildVersionNumber()

Returns the version number of the headers of the TLS library that Nt was built with.

See also sslLibraryBuildVersionString().

[static] QString QSslSocket::sslLibraryBuildVersionString()

Returns the version of the headers of the TLS library that Nt was built with, as text.

See also sslLibraryBuildVersionNumber().

[static] long QSslSocket::sslLibraryVersionNumber()

Returns the version number of the TLS library in use, OpenSSL or Mbed TLS.

See also sslLibraryVersionString().

[static] QString QSslSocket::sslLibraryVersionString()

Returns the version of the TLS library in use, as text.

See also sslLibraryVersionNumber().

[slot] void QSslSocket::startClientEncryption()

Starts a client handshake on a connection that is already established.

See also startServerEncryption() and encrypted().

[slot] void QSslSocket::startServerEncryption()

Starts a server handshake on a connection that is already established. A local certificate and private key must be set.

See also QSslServer, setLocalCertificate() and setPrivateKey().

[static] bool QSslSocket::supportsSsl()

Returns true. QSslSocket exists only in builds with a TLS library: OpenSSL, or Mbed TLS on Zephyr.

bool QSslSocket::waitForEncrypted(int msecs = 30000)

Waits up to msecs milliseconds for the handshake to finish, processing socket events meanwhile. A negative value waits forever. Returns true if the connection is encrypted.

See also encrypted().

[override, protected] qint64 QSslSocket::writeData(const char *data, qint64 maxSize)

Reimplements QTcpSocket::writeData().