Класс QSslSocket

Класс QSslSocket предоставляет сокет с SSL-шифрованием для клиентов и серверов. Подробнее...

• Список всех членов, включая унаследованные

Примечание: Все функции в этом классе являются перевходобезопасными.

Общедоступные типы

Общедоступные функции

Реализованные общедоступные функции

Public Slots

Signals

Static Public Members

Reimplemented Protected Functions

Related Non-Members

Detailed Description

QSslSocket устанавливает защищённое, зашифрованное TCP-соединение, которое можно использовать для передачи зашифрованных данных. Он может работать как в режиме клиента, так и в режиме сервера, и поддерживает современные протоколы SSL, включая SSL 3 и TLS 1.2. По умолчанию QSslSocket использует только протоколы SSL, которые считаются безопасными (QSsl::SecureProtocols), но вы можете изменить протокол SSL, вызвав setProtocol(), если это сделано до начала рукопожатия.

Шифрование SSL работает поверх существующего TCP-потока после того, как сокет переходит в состояние ConnectedState. Существует два простых способа установить защищённое соединение с помощью QSslSocket: с немедленным SSL-рукопожатием или с отложенным SSL-рукопожатием, происходящим после того, как соединение было установлено в незашифрованном режиме.

Наиболее распространённый способ использования QSslSocket — создание объекта и запуск защищённого соединения, вызвав connectToHostEncrypted(). Этот метод запускает немедленное SSL-рукопожатие после того, как соединение будет установлено.

QSslSocket *socket = new QSslSocket(this);
connect(socket, SIGNAL(encrypted()), this, SLOT(ready()));

socket->connectToHostEncrypted("imap.example.com", 993);

Как и с обычным QTcpSocket, QSslSocket переходит в состояния HostLookupState, ConnectingState и, наконец, ConnectedState, если соединение успешно. Затем автоматически запускается рукопожатие, и если оно успешно, издаётся сигнал encrypted(), чтобы указать, что сокет перешёл в зашифрованное состояние и готов к использованию.

Обратите внимание, что данные могут быть записаны в сокет сразу после возвращения из connectToHostEncrypted() (т.е. до того, как будет издан сигнал encrypted()). Данные размещаются в очереди в QSslSocket до момента выдачи сигнала encrypted().

Пример использования отложенного SSL-рукопожатия для защиты существующего соединения — случай, когда SSL-сервер защищает входящее соединение. Предположим, что вы создаёте класс SSL-сервера как подкласс QTcpServer. Вы бы переопределили QTcpServer::incomingConnection() чем-то вроде примера ниже, который сначала создаёт экземпляр QSslSocket, а затем вызывает setSocketDescriptor(), чтобы установить дескриптор нового сокета на существующий, переданный ему. Затем он инициирует SSL-рукопожатие, вызвав startServerEncryption().

void SslServer::incomingConnection(qintptr socketDescriptor)
{
    QSslSocket *serverSocket = new QSslSocket;
    if (serverSocket->setSocketDescriptor(socketDescriptor)) {
        addPendingConnection(serverSocket);
        connect(serverSocket, &QSslSocket::encrypted, this, &SslServer::ready);
        serverSocket->startServerEncryption();
    } else {
        delete serverSocket;
    }
}

Если произошла ошибка, QSslSocket испускает сигнал sslErrors(). В этом случае, если не предприняты действия для игнорирования ошибки(ошибок), соединение прерывается. Чтобы продолжить, несмотря на возникновение ошибки, можно вызвать ignoreSslErrors(), либо изнутри этого слота после возникновения ошибки, либо в любое время после создания QSslSocket и до попытки подключения. Это позволит QSslSocket игнорировать ошибки, которые возникают при установлении идентичности удалённого узла. Игнорирование ошибок во время рукопожатия SSL следует использовать с осторожностью, так как фундаментальной характеристикой защищённых соединений является то, что они должны быть установлены с успешным рукопожатием.

После шифрования вы используете QSslSocket как обычный QTcpSocket. Когда испускается readyRead(), вы можете вызвать read(), canReadLine() и readLine(), или getChar() для чтения дешифрованных данных из внутреннего буфера QSslSocket, и вы можете вызвать write() или putChar() для записи данных обратно удалённому узлу. QSslSocket автоматически зашифрует написанные данные, и испустит encryptedBytesWritten() после того, как данные будут записаны на удалённый узел.

Для удобства, QSslSocket поддерживает блокирующие функции QTcpSocket: waitForConnected(), waitForReadyRead(), waitForBytesWritten() и waitForDisconnected(). Он также предоставляет waitForEncrypted(), который заблокирует вызывающую нить до тех пор, пока не будет установлено зашифрованное соединение.

QSslSocket предоставляет обширный, удобный в использовании API для обработки криптографических шифров, закрытых ключей и локальных, удалённых и сертификатов Удостоверяющего центра (УЦ). Он также предоставляет API для обработки ошибок, которые возникают во время фазы рукопожатия.

Следующие функции также могут быть настраиваемы:

• Набор шифров сокета можно настроить до фазы рукопожатия с помощью QSslConfiguration::setCiphers() и QSslConfiguration::setDefaultCiphers().
• Локальный сертификат и закрытый ключ сокета можно настроить до фазы рукопожатия с помощью setLocalCertificate() и setPrivateKey().
• База данных сертификатов УЦ можно расширить и настроить с помощью QSslConfiguration::addCaCertificate(), QSslConfiguration::addCaCertificates().

Чтобы расширить список стандартных сертификатов УЦ, используемых сокетами SSL во время фазы рукопожатия SSL, необходимо обновить конфигурацию по умолчанию, как показано в примере ниже:

Примечание: Если доступны, корневые сертификаты в Unix (за исключением macOS) будут загружаться по требованию из стандартных каталогов сертификатов. Если вы не хотите загружать корневые сертификаты по требованию, вам нужно вызвать QSslConfiguration::defaultConfiguration().setCaCertificates() до того, как в вашем приложении произойдёт первое рукопожатие SSL (например, передав QSslSocket::systemCaCertificates() в него), или вызвать QSslConfiguration::defaultConfiguration()::setCaCertificates() на вашем экземпляре QSslSocket перед SSL рукопожатием.

Для получения дополнительной информации о шифрах и сертификатах обратитесь к QSslCipher и QSslCertificate.

Этот продукт включает в себя программное обеспечение, разработанное проектом OpenSSL для использования в наборе инструментов OpenSSL (http://www.openssl.org/).

Примечание: Обратите внимание на разницу между сигналом bytesWritten() и сигналом encryptedBytesWritten(). Для QTcpSocket сигнал bytesWritten() будет испущен, как только данные будут записаны в TCP-сокет. Для QSslSocket, bytesWritten() будет испущен, когда данные будут шифроваться, а encryptedBytesWritten() будет испущен, как только данные будут записаны в TCP-сокет.

См. также QSslCertificate, QSslCipher и QSslError.

Документация по типам элементов

enum QSslSocket::PeerVerifyMode

Описывает режимы проверки удалённого узла для QSslSocket. Режим по умолчанию — AutoVerifyPeer, который выбирает соответствующий режим в зависимости от QSocket::SslMode сокета.

См. также QSslSocket::peerVerifyMode().

enum QSslSocket::SslMode

Описывает режимы соединения, доступные для QSslSocket.

Документация по функциям-членам

QSslSocket::QSslSocket(QObject *parent = nullptr)

Создаёт объект QSslSocket. parent передаётся конструктору QObject. Набор шифров нового сокета устанавливается на набор, возвращаемый статическим методом defaultCiphers().

void QSslSocket::alertReceived(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QSslSocket испускает этот сигнал, если от удалённого узла было получено сообщение об ошибке. level указывает, была ли ошибка критической или предупреждением. type — код, объясняющий, почему была отправлена ошибка. Если доступно текстовое описание сообщения об ошибке, оно предоставляется в description.

Примечание: Сигнал предназначен в основном для информационных и отладочных целей и не требует обработки в приложении. Если ошибка была критической, обработчик позаботится о закрытии соединения.

Примечание: Не все среды поддержки поддерживают эту функциональность.

См. также alertSent(), QSsl::AlertLevel и QSsl::AlertType.

void QSslSocket::alertSent(QSsl::AlertLevel level, QSsl::AlertType type, const QString &description)

QSslSocket испускает этот сигнал, если сообщение об ошибке было отправлено удалённому узлу. level описывает, было ли это предупреждением или критической ошибкой. type даёт код сообщения об ошибке. Если доступно текстовое описание сообщения об ошибке, оно предоставляется в description.

Примечание: Этот сигнал в основном информативный и может использоваться для отладки, обычно он не требует каких-либо действий от приложения.

Примечание: Не все среды поддержки поддерживают эту функциональность.

См. также alertReceived(), QSsl::AlertLevel и QSsl::AlertType.

void QSslSocket::encrypted()

Этот сигнал испускается, когда QSslSocket переходит в зашифрованный режим. После испускания этого сигнала QSslSocket::isEncrypted() вернёт true, и все последующие передачи по сокету будут зашифрованы.

См. также QSslSocket::connectToHostEncrypted() и QSslSocket::isEncrypted().

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

Этот сигнал испускается, когда QSslSocket записывает свои зашифрованные данные в сеть. Параметр written содержит количество успешно записанных байтов.

См. также QIODevice::bytesWritten().

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

QSslSocket испускает этот сигнал, если была обнаружена ошибка проверки сертификата и если предварительный отчёт об ошибках был включён в QSslConfiguration. Приложение должно проверить ошибку error и решить, продолжать ли рукопожатие или прервать его и отправить сообщение об ошибке партнёру. Подключение сигнала и слота должно быть прямым.

См. также continueInterruptedHandshake(), sslErrors() и QSslConfiguration::setHandshakeMustInterruptOnError().

[slot] void QSslSocket::ignoreSslErrors()

Этот слот сообщает QSslSocket игнорировать ошибки во время фазы рукопожатия QSslSocket и продолжить подключение. Если вы хотите продолжить подключение даже при возникновении ошибок во время фазы рукопожатия, то вы должны вызвать этот слот, либо из слота, подключённого к sslErrors(), либо перед фазой рукопожатия. Если вы не вызовете этот слот, ни в ответ на ошибки, ни перед рукопожатием, подключение будет разорвано после испускания сигнала sslErrors().

Если ошибок во время фазы рукопожатия SSL (т.е., идентичность партнёра установлена без проблем) не возникло, QSslSocket не будет испускать сигнал sslErrors(), и вызывать эту функцию не нужно.

Предупреждение: Убедитесь, что пользователь всегда проверяет ошибки, сообщаемые сигналом sslErrors(), и вызывайте этот метод только после подтверждения пользователя о том, что продолжение разрешено. Если возникнут неожиданные ошибки, подключение следует прервать. Вызов этого метода без проверки фактических ошибок, скорее всего, создаст риск безопасности для вашего приложения. Используйте его с большой осторожностью!

См. также sslErrors().

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

Этот сигнал испускается, когда QSslSocket переходит от режима QSslSocket::UnencryptedMode к QSslSocket::SslClientMode или QSslSocket::SslServerMode. mode — новый режим.

См. также QSslSocket::mode().

[signal, since 5.15] void QSslSocket::newSessionTicketReceived()

Если протокол TLS 1.3 был согласован во время рукопожатия, QSslSocket испускает этот сигнал после получения сообщения NewSessionTicket. Срок действия сессии и подсказка о сроке действия маркера сессии обновляются в конфигурации сокета. Сессия может использоваться для возобновления сессии (и сокращённого рукопожатия) в будущих подключениях TLS.

Примечание: Эта функциональность включена только с бэкэндом OpenSSL и требует OpenSSL версии 1.1.1 или выше.

Эта функция была добавлена в Qt 5.15.

См. также QSslSocket::sslConfiguration(), QSslConfiguration::sessionTicket() и QSslConfiguration::sessionTicketLifeTimeHint().

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

QSslSocket может испускать этот сигнал несколько раз во время рукопожатия SSL, прежде чем будет установлено шифрование, чтобы указать, что возникла ошибка при установлении идентичности партнёра. Ошибка error обычно указывает на то, что QSslSocket не может надёжно идентифицировать партнёра.

Этот сигнал предоставляет вам раннее предупреждение о проблемах. Подключив этот сигнал, вы можете вручную прервать подключение внутри подключенного слота до завершения рукопожатия. Если никаких действий не предпринято, QSslSocket продолжит испускать QSslSocket::sslErrors().

См. также sslErrors().

[signal, since 5.5] void QSslSocket::preSharedKeyAuthenticationRequired(QSslPreSharedKeyAuthenticator *authenticator)

QSslSocket испускает этот сигнал, когда он согласовывает набор шифрования PSK, и поэтому требуется аутентификация PSK.

При использовании PSK клиент должен отправить серверу действительную личность и действительный предварительно согласованный ключ, чтобы рукопожатие SSL продолжилось. Приложения могут предоставить эту информацию в слоте, подключенном к этому сигналу, заполнив переданный объект authenticator в соответствии со своими потребностями.

Примечание: Игнорирование этого сигнала или не предоставление необходимых учетных данных приведёт к неудаче рукопожатия и, следовательно, к прерыванию подключения.

Примечание: Объект authenticator принадлежит сокету и не должен удаляться приложением.

Эта функция была добавлена в Qt 5.5.

См. также QSslPreSharedKeyAuthenticator.

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

QSslSocket испускает этот сигнал после рукопожатия SSL, чтобы указать, что возникла одна или несколько ошибок при установлении идентичности партнёра. Ошибки обычно указывают на то, что QSslSocket не может надёжно идентифицировать партнёра. Если не предпринято никаких действий, подключение будет прервано после испускания этого сигнала.

Если вы хотите продолжить подключение несмотря на возникшие ошибки, вы должны вызвать QSslSocket::ignoreSslErrors() изнутри слота, подключенного к этому сигналу. Если вам нужно получить доступ к списку ошибок впоследствии, вы можете вызвать sslHandshakeErrors().

errors содержит одну или несколько ошибок, которые препятствуют QSslSocket в проверке идентичности партнёра.

Примечание: Вы не можете использовать Qt::QueuedConnection при подключении к этому сигналу, в противном случае вызов QSslSocket::ignoreSslErrors() не будет иметь эффекта.

См. также peerVerifyError().

[slot] void QSslSocket::startClientEncryption()

Начинает отложенное рукопожатие SSL для подключения клиента. Эту функцию можно вызвать, когда сокет находится в состоянии ConnectedState, но всё ещё в режиме UnencryptedMode. Если он ещё не подключен или уже зашифрован, эта функция не оказывает влияния.

Клиенты, которые реализуют функциональность STARTTLS, часто используют отложенные рукопожатия SSL. Большинство других клиентов могут избежать вызова этой функции напрямую, используя connectToHostEncrypted() вместо этого, что автоматически выполняет рукопожатие.

См. также connectToHostEncrypted() и startServerEncryption().

[slot] void QSslSocket::startServerEncryption()

Начинает отложенное рукопожатие SSL для серверного подключения. Эту функцию можно вызвать, когда сокет находится в состоянии ConnectedState, но всё ещё в режиме UnencryptedMode. Если он не подключен или уже зашифрован, функция не оказывает влияния.

Для серверных сокетов вызов этой функции является единственным способом инициировать рукопожатие SSL. Большинство серверов вызовут эту функцию сразу после получения подключения или в результате получения команды определённого протокола для перехода в режим SSL (например, сервер может ответить на получение строки "STARTTLS\r\n" вызовом этой функции).

Наиболее распространённый способ реализации SSL-сервера — создание подкласса QTcpServer и переопределение QTcpServer::incomingConnection(). Затем описатель возвращённого сокета передаётся в QSslSocket::setSocketDescriptor().

См. также connectToHostEncrypted() и startClientEncryption().

[virtual] QSslSocket::~QSslSocket()

Уничтожает QSslSocket.

[override virtual] bool QSslSocket::atEnd() const

Переопределяет: QIODevice::atEnd() const.

[override virtual] qint64 QSslSocket::bytesAvailable() const

Переопределяет: QAbstractSocket::bytesAvailable() const.

Возвращает количество расшифрованных байтов, которые немедленно доступны для чтения.

[override virtual] qint64 QSslSocket::bytesToWrite() const

Переопределяет: QAbstractSocket::bytesToWrite() const.

Возвращает количество незашифрованных байтов, которые ожидают шифрования и записи в сеть.

[override virtual] bool QSslSocket::canReadLine() const

Переопределяет: QIODevice::canReadLine() const.

Возвращает true, если можно прочитать одну строку (оканчивающуюся одиночным ASCII-символом '\n') дешифрованных символов; в противном случае возвращается false.

[override virtual] void QSslSocket::close()

Переопределяет: QAbstractSocket::close().

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

Начинает зашифрованное подключение к устройству hostName на порту port, используя mode в качестве OpenMode. Это эквивалентно вызову connectToHost() для установления соединения, за которым следует вызов startClientEncryption(). Параметр protocol может использоваться для указания сетевого протокола (например, IPv4 или IPv6).

QSslSocket сначала переходит в состояние HostLookupState. Затем, после перехода в цикл событий или в одну из функций waitFor..., он переходит в состояние ConnectingState, испускает сигнал connected() и затем инициирует SSL-клиентский обмен данными. При каждом изменении состояния QSslSocket испускает сигнал stateChanged().

После инициирования SSL-клиентского обмена данными, если идентичность удалённого узла не может быть установлена, испускается сигнал sslErrors(). Если вы хотите игнорировать ошибки и продолжить подключение, вы должны вызвать ignoreSslErrors(), либо изнутри слотовой функции, подключённой к сигналу sslErrors(), либо до перехода в зашифрованный режим. Если ignoreSslErrors() не вызывается, соединение прерывается, испускается сигнал disconnected(), и QSslSocket возвращается в состояние UnconnectedState.

Если SSL-обмен данными завершается успешно, QSslSocket испускает сигнал encrypted().

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

socket.connectToHostEncrypted("imap", 993);
socket->write("1 CAPABILITY\r\n");

Примечание: Приведенный выше пример показывает, что текст может быть записан в сокет сразу после запроса зашифрованного соединения, до того, как будет испущен сигнал encrypted(). В таких случаях текст помещается в очередь объекта и записывается в сокет после установления соединения и испускания сигнала encrypted().

По умолчанию mode равен ReadWrite.

Если вы хотите создать QSslSocket на стороне сервера соединения, вы должны вместо этого вызвать startServerEncryption() при получении входящего соединения через QTcpServer.

См. также connectToHost(), startClientEncryption(), waitForConnected() и waitForEncrypted().

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

Это перегруженный метод.

В дополнение к исходному поведению connectToHostEncrypted, этот перегруженный метод позволяет использовать другое имя хоста (sslPeerName) для проверки сертификата вместо используемого для TCP-соединения (hostName).

См. также connectToHostEncrypted().

[since 6.0] void QSslSocket::continueInterruptedHandshake()

Если приложение хочет завершить обмен данными даже после получения сигнала handshakeInterruptedOnError(), оно должно вызвать эту функцию. Этот вызов должен выполняться из слотовой функции, прикреплённой к сигналу. Подключение сигнал-слот должно быть прямым.

Эта функция была введена в Qt 6.0.

См. также handshakeInterruptedOnError() и QSslConfiguration::setHandshakeMustInterruptOnError().

qint64 QSslSocket::encryptedBytesAvailable() const

Возвращает количество зашифрованных байтов, ожидающих дешифрования. Обычно эта функция возвращает 0, потому что QSslSocket дешифрует входящие данные сразу, как только это возможно.

qint64 QSslSocket::encryptedBytesToWrite() const

Возвращает количество зашифрованных байтов, ожидающих записи в сеть.

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

Это перегруженный метод.

Этот метод сообщает QSslSocket игнорировать только ошибки, указанные в errors.

Примечание: Поскольку большинство ошибок SSL связаны с сертификатом, для большинства из них необходимо указать ожидаемый сертификат, к которому относится эта ошибка SSL. Например, если вы хотите подключиться к серверу, использующему самозаверяемый сертификат, рассмотрите следующий фрагмент:

QList<QSslCertificate> cert = QSslCertificate::fromPath(QLatin1String("server-certificate.pem"));
QSslError error(QSslError::SelfSignedCertificate, cert.at(0));
QList<QSslError> expectedSslErrors;
expectedSslErrors.append(error);

QSslSocket socket;
socket.ignoreSslErrors(expectedSslErrors);
socket.connectToHostEncrypted("server.tld", 443);

Несколько вызовов этой функции заменят список ошибок, переданных в предыдущих вызовах. Вы можете очистить список ошибок, которые вы хотите игнорировать, вызвав эту функцию со списком пустым.

См. также sslErrors() и sslHandshakeErrors().

bool QSslSocket::isEncrypted() const

Возвращает true, если сокет зашифрован; в противном случае возвращает false.

Зашифрованный сокет шифрует все данные, которые записываются с помощью вызова write() или putChar() перед записью данных в сеть, и дешифрует все входящие данные при получении данных из сети, до вызова read(), readLine() или getChar().

QSslSocket испускает сигнал encrypted() при входе в зашифрованный режим.

Вы можете вызвать sessionCipher(), чтобы узнать, какой криптографический алгоритм используется для шифрования и дешифрования ваших данных.

См. также mode().

QSslCertificate QSslSocket::localCertificate() const

Возвращает локальный сертификат сокета certificate, или пустой сертификат, если локальный сертификат не назначен.

См. также setLocalCertificate() и privateKey().

[since 5.1] QList<QSslCertificate> QSslSocket::localCertificateChain() const

Возвращает цепочку локальных сертификатов сокета certificate, или пустой список, если локальные сертификаты не назначены.

Эта функция была введена в Qt 5.1.

См. также setLocalCertificateChain().

QSslSocket::SslMode QSslSocket::mode() const

Возвращает текущий режим сокета; либо UnencryptedMode, где QSslSocket ведёт себя идентично QTcpSocket, или один из SslClientMode или SslServerMode, где клиент либо ведёт переговоры, либо находится в зашифрованном режиме.

При изменении режима QSslSocket испускает сигнал modeChanged()

См. также SslMode.

[since 5.13] QList<QOcspResponse> QSslSocket::ocspResponses() const

Эта функция возвращает ответы протокола Online Certificate Status Protocol, которые сервер может отправить во время TLS-обмена данными с использованием OCSP-стаплинга. Список пустой, если определённый ответ или вообще никакой ответ не был получен.

Эта функция была введена в Qt 5.13.

См. также QSslConfiguration::setOcspStaplingEnabled().

QSslCertificate QSslSocket::peerCertificate() const

Возвращает цифровой сертификат удалённого узла (т.е., непосредственный сертификат узла, к которому вы подключены), или нулевой сертификат, если удалённый узел не предоставил сертификат.

Сертификат удалённого узла автоматически проверяется на стадии обмена данными, поэтому эта функция обычно используется для получения сертификата для отображения или для диагностики соединения. Он содержит информацию о удалённом узле, включая его имя хоста, издателя сертификата и открытый ключ удалённого узла.

Поскольку сертификат удалённого узла устанавливается на стадии обмена данными, обращение к сертификату удалённого узла безопасно из слотовой функции, подключённой к сигналу sslErrors() или encrypted().

Если возвращается нулевой сертификат, это может означать, что рукопожатие SSL завершилось неудачно, или что у узла, к которому вы подключены, нет сертификата, или что нет подключения.

Если вы хотите проверить полную цепочку сертификатов удалённого узла, используйте peerCertificateChain() для получения всех сертификатов сразу.

См. также peerCertificateChain().

QList<QSslCertificate> QSslSocket::peerCertificateChain() const

Возвращает цепочку цифровых сертификатов удалённого узла или пустой список сертификатов.

Сертификаты удалённого узла проверяются автоматически во время фазы рукопожатия. Эта функция обычно используется для получения сертификатов для отображения или для диагностики соединения. Сертификаты содержат информацию об удалённом узле и издателях сертификатов, включая имя узла, имена издателей и открытые ключи издателей.

Сертификаты удалённого узла устанавливаются в QSslSocket во время фазы рукопожатия, поэтому безопасно вызывать эту функцию из слота, подключённого к сигналу sslErrors() или сигналу encrypted().

Если возвращается пустой список, это может означать, что рукопожатие SSL завершилось неудачно, или что у узла, к которому вы подключены, нет сертификата, или что нет подключения.

Если вам нужен только непосредственный сертификат удалённого узла, используйте peerCertificate().

См. также peerCertificate().

int QSslSocket::peerVerifyDepth() const

Возвращает максимальное количество сертификатов в цепочке сертификатов удалённого узла, которые должны быть проверены во время фазы рукопожатия SSL, или 0 (по умолчанию), если максимальная глубина не задана, что указывает на то, что вся цепочка сертификатов должна быть проверена.

Сертификаты проверяются в порядке выдачи, начиная с собственного сертификата удалённого узла, затем с сертификата его издателя и так далее.

См. также setPeerVerifyDepth() и peerVerifyMode().

QSslSocket::PeerVerifyMode QSslSocket::peerVerifyMode() const

Возвращает режим проверки. Этот режим определяет, должен ли QSslSocket запрашивать сертификат от удалённого узла (т.е. клиент запрашивает сертификат у сервера или сервер запрашивает сертификат у клиента), и должен ли он требовать, чтобы этот сертификат был действителен.

Режим по умолчанию — AutoVerifyPeer, который указывает QSslSocket использовать VerifyPeer для клиентов и QueryPeer для серверов.

См. также setPeerVerifyMode(), peerVerifyDepth() и mode().

QString QSslSocket::peerVerifyName() const

Возвращает имя хоста для проверки сертификата, заданное setPeerVerifyName или connectToHostEncrypted.

См. также setPeerVerifyName() и connectToHostEncrypted().

QSslKey QSslSocket::privateKey() const

Возвращает закрытый ключ данного сокета.

См. также setPrivateKey() и localCertificate().

QSsl::SslProtocol QSslSocket::protocol() const

Возвращает протокол SSL сокета. По умолчанию используется QSsl::SecureProtocols.

См. также setProtocol().

[override virtual protected] qint64 QSslSocket::readData(char *data, qint64 maxlen)

Переопределяет: QAbstractSocket::readData(char *data, qint64 maxSize).

[override virtual, since 5.0] void QSslSocket::resume()

Переопределяет: QAbstractSocket::resume().

Продолжает передачу данных по сокету после его приостановки. Если для этого сокета был вызван "setPauseMode(QAbstractSocket::PauseOnSslErrors);" и был получен сигнал sslErrors(), для продолжения работы сокета необходимо вызвать этот метод.

Эта функция была введена в Qt 5.0.

См. также QAbstractSocket::pauseMode() и QAbstractSocket::setPauseMode().

QSslCipher QSslSocket::sessionCipher() const

Возвращает криптографическое шифрование шифра сокета или нулевой шифр, если соединение не зашифровано. Шифр сокета для сеанса устанавливается во время фазы рукопожатия. Шифр используется для шифрования и дешифрования данных, передаваемых через сокет.

QSslSocket также предоставляет функции для установки упорядоченного списка шифров, из которых фаза рукопожатия в конечном итоге выберет сеансовый шифр. Этот упорядоченный список должен быть создан до начала фазы рукопожатия.

См. также QSslConfiguration::ciphers(), QSslConfiguration::setCiphers(), QSslConfiguration::setCiphers(), QSslConfiguration::ciphers() и QSslConfiguration::supportedCiphers().

[since 5.4] QSsl::SslProtocol QSslSocket::sessionProtocol() const

Возвращает протокол SSL/TLS сокета или UnknownProtocol, если соединение не зашифровано. Протокол сокета для сеанса устанавливается во время фазы рукопожатия.

Эта функция была введена в Qt 5.4.

См. также protocol() и setProtocol().

void QSslSocket::setLocalCertificate(const QSslCertificate &certificate)

Устанавливает локальный сертификат сокета в certificate. Локальный сертификат необходим, если вам нужно подтвердить свою личность для удалённого узла. Он используется вместе с закрытым ключом; если вы установите локальный сертификат, вы также должны установить закрытый ключ.

Локальный сертификат и закрытый ключ всегда необходимы для серверных сокетов, но также редко используются клиентскими сокетами, если сервер требует аутентификации клиента.

Примечание: Безопасный транспорт SSL на macOS может обновлять стандартный хранилище ключей (по умолчанию — хранилище ключей вашей учётной записи) путём импорта локальных сертификатов и ключей. Это также может привести к появлению системных диалоговых окон, запрашивающих разрешение при использовании этих закрытых ключей в приложении. Если такое поведение нежелательно, установите переменную среды QT_SSL_USE_TEMPORARY_KEYCHAIN с ненулевым значением; это заставит QSslSocket использовать своё временное хранилище ключей.

См. также localCertificate() и setPrivateKey().

void QSslSocket::setLocalCertificate(const QString &path, QSsl::EncodingFormat format = QSsl::Pem)

Это перегруженная функция.

Устанавливает локальный сертификат сокета на первый найденный в файле path, который анализируется в соответствии с указанным format.

[since 5.1] void QSslSocket::setLocalCertificateChain(const QList<QSslCertificate> &localChain)

Устанавливает цепочку сертификатов, которые будут представлены удалённому узлу во время рукопожатия SSL, на localChain.

Эта функция была введена в Qt 5.1.

См. также localCertificateChain() и QSslConfiguration::setLocalCertificateChain().

void QSslSocket::setPeerVerifyDepth(int depth)

Устанавливает максимальное количество сертификатов в цепочке сертификатов удалённого узла, которые должны быть проверены во время фазы рукопожатия SSL, на depth. Установка глубины 0 означает, что максимальная глубина не установлена, что указывает на то, что вся цепочка сертификатов должна быть проверена.

Сертификаты проверяются в порядке выдачи, начиная с собственного сертификата удалённого узла, затем с сертификата его издателя и так далее.

См. также peerVerifyDepth() и setPeerVerifyMode().

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

Устанавливает режим проверки сокета на mode. Этот режим определяет, должен ли QSslSocket запрашивать сертификат от удалённого узла (т.е. клиент запрашивает сертификат у сервера или сервер запрашивает сертификат у клиента), и должен ли он требовать, чтобы этот сертификат был действителен.

Режим по умолчанию — AutoVerifyPeer, который указывает QSslSocket использовать VerifyPeer для клиентов и QueryPeer для серверов.

Установка этого режима после начала шифрования не влияет на текущее соединение.

См. также peerVerifyMode(), setPeerVerifyDepth() и mode().

void QSslSocket::setPeerVerifyName(const QString &hostName)

Устанавливает другое имя хоста, заданное hostName, для проверки сертификата вместо имени, используемого для TCP-соединения.

См. также peerVerifyName() и connectToHostEncrypted().

void QSslSocket::setPrivateKey(const QSslKey &key)

Устанавливает закрытый ключ сокета на key. Закрытый ключ и локальный сертификат используются клиентами и серверами, которые должны подтвердить свою личность для SSL-партнеров.

И ключ, и локальный сертификат необходимы, если вы создаёте SSL-серверный сокет. Если вы создаёте SSL-клиентский сокет, ключ и локальный сертификат необходимы, если ваш клиент должен идентифицироваться для SSL-сервера.

См. также privateKey() и setLocalCertificate().

void QSslSocket::setPrivateKey(const QString &fileName, QSsl::KeyAlgorithm algorithm = QSsl::Rsa, QSsl::EncodingFormat format = QSsl::Pem, const QByteArray &passPhrase = QByteArray())

Это перегруженный метод.

Читает строку в файле fileName и декодирует её, используя указанный algorithm и формат кодирования format, чтобы создать SSL-ключ.

Если закодированный ключ зашифрован, passPhrase используется для его расшифровки.

Закрытый ключ сокета устанавливается на созданный ключ. Закрытый ключ и локальный сертификат используются клиентами и серверами, которые должны подтвердить свою личность для SSL-партнеров.

И ключ, и локальный сертификат необходимы, если вы создаёте SSL-серверный сокет. Если вы создаёте SSL-клиентский сокет, ключ и локальный сертификат необходимы, если ваш клиент должен идентифицироваться для SSL-сервера.

См. также privateKey() и setLocalCertificate().

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

Устанавливает SSL-протокол сокета на protocol. Это повлияет на следующий инициированный обмен; вызов этой функции для уже зашифрованного сокета не повлияет на протокол сокета.

См. также protocol().

void QSslSocket::setReadBufferSize(qint64 size)

Переопределяет: QAbstractSocket::setReadBufferSize(qint64 size).

Устанавливает размер внутреннего буфера чтения QSslSocket на size байт.

bool QSslSocket::setSocketDescriptor(qintptr socketDescriptor, QAbstractSocket::SocketState state = ConnectedState, QIODeviceBase::OpenMode openMode = ReadWrite)

Переопределяет: QAbstractSocket::setSocketDescriptor(qintptr socketDescriptor, QAbstractSocket::SocketState socketState, QIODeviceBase::OpenMode openMode).

Инициализирует QSslSocket с помощью системного дескриптора сокета socketDescriptor. Возвращает true, если socketDescriptor принят как допустимый дескриптор сокета; в противном случае возвращает false. Сокет открывается в режиме, указанном openMode, и переходит в состояние, указанное state.

Примечание: Невозможно инициализировать два сокета с одним и тем же системным дескриптором сокета.

См. также socketDescriptor().

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

Переопределяет: QAbstractSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value).

Устанавливает заданный option на значение, описанное value.

См. также socketOption().

void QSslSocket::setSslConfiguration(const QSslConfiguration &configuration)

Устанавливает SSL-настройку сокета на содержимое configuration. Эта функция устанавливает локальный сертификат, шифры, закрытый ключ и сертификаты CA на те, которые хранятся в configuration.

Невозможно установить поля, связанные с SSL-состоянием.

См. также sslConfiguration(), setLocalCertificate(), setPrivateKey(), QSslConfiguration::setCaCertificates(), и QSslConfiguration::setCiphers().

qint64 QSslSocket::skipData(qint64 maxSize)

Переопределяет: QAbstractSocket::skipData(qint64 maxSize).

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

Переопределяет: QAbstractSocket::socketOption(QAbstractSocket::SocketOption option).

Возвращает значение параметра option.

См. также setSocketOption().

QSslConfiguration QSslSocket::sslConfiguration() const

Возвращает состояние SSL-настройки сокета. По умолчанию SSL-настройки сокета используют стандартные шифры, стандартные сертификаты CA, без локального закрытого ключа или сертификата.

SSL-настройки также содержат поля, которые могут изменяться со временем без уведомления.

См. также setSslConfiguration(), localCertificate(), peerCertificate(), peerCertificateChain(), sessionCipher(), privateKey(), QSslConfiguration::ciphers(), и QSslConfiguration::caCertificates().

QList<QSslError> QSslSocket::sslHandshakeErrors() const

Возвращает список последних ошибок SSL, которые произошли. Этот список совпадает с тем, который QSslSocket передаёт через сигнал sslErrors(). Если соединение было зашифровано без ошибок, эта функция вернёт пустой список.

Эта функция была добавлена в Qt 5.15.

См. также connectToHostEncrypted().

long QSslSocket::sslLibraryBuildVersionNumber()

Возвращает номер версии используемой SSL-библиотеки во время компиляции. Если поддержка SSL недоступна, возвращает неопределённое значение.

Эта функция была добавлена в Qt 5.4.

См. также sslLibraryVersionNumber().

QString QSslSocket::sslLibraryBuildVersionString()

Возвращает строку версии используемой SSL-библиотеки во время компиляции. Если поддержка SSL недоступна, возвращает пустое значение.

Эта функция была добавлена в Qt 5.4.

См. также sslLibraryVersionString().

long QSslSocket::sslLibraryVersionNumber()

Возвращает номер версии используемой SSL-библиотеки. Обратите внимание, что это версия библиотеки, используемой во время выполнения, а не во время компиляции. Если поддержка SSL недоступна, возвращает неопределённое значение.

Эта функция была добавлена в Qt 5.0.

QString QSslSocket::sslLibraryVersionString()

Возвращает строку версии используемой SSL-библиотеки. Обратите внимание, что это версия библиотеки, используемой во время выполнения, а не во время компиляции. Если поддержка SSL недоступна, возвращает пустое значение.

Эта функция была добавлена в Qt 5.0.

bool QSslSocket::supportsSsl()

Возвращает true, если платформа поддерживает SSL; в противном случае возвращает false. Если платформа не поддерживает SSL, соединение завершится с ошибкой.

bool QSslSocket::waitForBytesWritten(int msecs = 30000)

Переопределяет: QAbstractSocket::waitForBytesWritten(int msecs).

bool QSslSocket::waitForConnected(int msecs = 30000)

Переопределяет: QAbstractSocket::waitForConnected(int msecs).

Ожидает подключения сокета или msecs миллисекунд, в зависимости от того, что произойдет раньше. Если соединение установлено, эта функция возвращает true; в противном случае она возвращает false.

См. также QAbstractSocket::waitForConnected().

[override virtual] bool QSslSocket::waitForDisconnected(int msecs = 30000)

Переопределяет: QAbstractSocket::waitForDisconnected(int msecs).

Ожидает, пока сокет не будет отключен или msecs миллисекунд, в зависимости от того, что произойдет раньше. Если соединение отключено, эта функция возвращает true; в противном случае возвращает false.

См. также QAbstractSocket::waitForDisconnected().

bool QSslSocket::waitForEncrypted(int msecs = 30000)

Ожидает, пока сокет завершит SSL-установление соединения и вызовет encrypted(), или msecs миллисекунд, в зависимости от того, что произойдет раньше. Если encrypted() был вызван, эта функция возвращает true; в противном случае (например, сокет отключён или SSL-установление соединения завершается неудачно), возвращается false.

В следующем примере ожидается до одной секунды, пока сокет будет зашифрован:

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

Если msecs равно -1, эта функция не будет вызывать таймаут.

См. также startClientEncryption(), startServerEncryption(), encrypted() и isEncrypted().

[override virtual] bool QSslSocket::waitForReadyRead(int msecs = 30000)

Переопределяет: QAbstractSocket::waitForReadyRead(int msecs).

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

Переопределяет: QAbstractSocket::writeData(const char *data, qint64 size).