Класс 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-handshake после установления соединения.

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

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

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

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

Пример использования отложенного SSL-handshake для защиты существующего соединения — случай, когда SSL-сервер защищает входящее соединение. Предположим, вы создали класс SSL-сервера как подкласс QTcpServer. Вы переопределите QTcpServer::incomingConnection() примерно как в примере ниже, сначала создав экземпляр QSslSocket, а затем вызвав setSocketDescriptor() для установки дескриптора нового сокета на существующий, переданный в качестве параметра. Затем инициализируется SSL-handshake вызовом 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-handshake следует применять с осторожностью, поскольку фундаментальной характеристикой защищенных соединений является их успешное установление.

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

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

QSslSocket socket;
socket.connectToHostEncrypted("http.example.com", 443);
if (!socket.waitForEncrypted()) {
    qDebug() << socket.errorString();
    return false;
}

socket.write("GET / HTTP/1.0\r\n\r\n");
while (socket.waitForReadyRead())
    qDebug() << socket.readAll().data();

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

Можно настроить следующие параметры:

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

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

QList<QSslCertificate> certificates = getCertificates();
QSslConfiguration configuration = QSslConfiguration::defaultConfiguration();
configuration.addCaCertificates(certificates);
QSslConfiguration::setDefaultConfiguration(configuration);

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

Дополнительную информацию о шифрах и сертификатах см. в QSslCipher и QSslCertificate.

Этот продукт включает в себя программное обеспечение, разработанное OpenSSL Project для использования в OpenSSL Toolkit (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. Набор шифров cipher нового сокета устанавливается в тот, который возвращает статический метод defaultCiphers().

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

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

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

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

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

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

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

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

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

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

[signal] 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-рукопожатия, прежде чем будет установлено шифрование, чтобы указать на возникновение ошибки при установлении личности узла. Ошибка, как правило, указывает на то, что 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.

[static, since 6.1] QString QSslSocket::activeBackend()

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

Примечание: При неявном выборе бэкенда по умолчанию QSslSocket отдает предпочтение нативным бэкендам, таким как SecureTransport на Darwin или Schannel на Windows.

Функция была добавлена в Qt 6.1.

См. также setActiveBackend() и availableBackends().

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

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

[static, since 6.1] QList<QString> QSslSocket::availableBackends()

Возвращает имена доступных в настоящее время бэкендов. Эти имена в нижнем регистре, например, "openssl", "securetransport", "schannel" (аналогично уже существующим именам функций для TLS-бэкендов в Qt).

Функция была добавлена в Qt 6.1.

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

[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().

[static, since 6.1] QList<QSsl::ImplementedClass> QSslSocket::implementedClasses(const QString &backendName = {})

Эта функция возвращает классы, специфичные для бэкенда, реализованные бэкендом с именем backendName. Пустое backendName понимается как запрос об активном бэкенде.

Функция была добавлена в Qt 6.1.

См. также QSsl::ImplementedClass, activeBackend() и isClassImplemented().

[static, since 6.1] bool QSslSocket::isClassImplemented(QSsl::ImplementedClass cl, const QString &backendName = {})

Возвращает true, если класс \cl реализован бэкендом с именем backendName. Пустое значение backendName понимается как запрос о текущем активном бэкенде.

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

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

bool QSslSocket::isEncrypted() const

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

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

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

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

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

[static, since 6.1] bool QSslSocket::isFeatureSupported(QSsl::SupportedFeature ft, const QString &backendName = {})

Возвращает true, если функция ft поддерживается бэкендом с именем backendName. Пустое значение backendName понимается как запрос о текущем активном бэкенде.

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

См. также QSsl::SupportedFeature и supportedFeatures().

[static, since 6.1] bool QSslSocket::isProtocolSupported(QSsl::SslProtocol protocol, const QString &backendName = {})

Возвращает true, если protocol поддерживается бэкендом с именем backendName. Пустое значение backendName понимается как запрос о текущем активном бэкенде.

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

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

QSslCertificate QSslSocket::localCertificate() const

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

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

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

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

Эта функция была добавлена в 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 stapling. Список пуст, если не получен определенный ответ или вообще не получен ни один ответ.

Эта функция была добавлена в 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

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

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().

[static, since 6.1] bool QSslSocket::setActiveBackend(const QString &backendName)

Возвращает true, если бэкенд с именем backendName был установлен в качестве активного бэкенда. backendName должен быть одним из имён, возвращаемых функцией availableBackends().

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

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

См. также activeBackend() и availableBackends().

void QSslSocket::setLocalCertificate(const QSslCertificate &certificate)

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

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

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

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

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

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

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

[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().

[override virtual] void QSslSocket::setReadBufferSize(qint64 size)

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

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

[override virtual] 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().

[override virtual] 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().

[override virtual protected] qint64 QSslSocket::skipData(qint64 maxSize)

Реализует: QAbstractSocket::skipData(qint64 maxSize).

[override virtual] 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().

[since 5.15] QList<QSslError> QSslSocket::sslHandshakeErrors() const

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

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

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

[static, since 5.4] long QSslSocket::sslLibraryBuildVersionNumber()

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

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

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

[static, since 5.4] QString QSslSocket::sslLibraryBuildVersionString()

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

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

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

[static, since 5.0] long QSslSocket::sslLibraryVersionNumber()

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

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

[static, since 5.0] QString QSslSocket::sslLibraryVersionString()

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

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

[static, since 6.1] QList<QSsl::SupportedFeature> QSslSocket::supportedFeatures(const QString &backendName = {})

Эта функция возвращает функции, поддерживаемые бэкендом с именем backendName. Пустое backendName понимается как запрос о текущем активном бэкенде.

Данная функция была добавлена в Qt 6.1.

См. также QSsl::SupportedFeature и activeBackend().

[static, since 6.1] QList<QSsl::SslProtocol> QSslSocket::supportedProtocols(const QString &backendName = {})

Если бэкенд с именем backendName доступен, эта функция возвращает список версий протоколов TLS, поддерживаемых этим бэкендом. Пустое backendName понимается как запрос о текущем активном бэкенде. В противном случае эта функция возвращает пустой список.

Данная функция была добавлена в Qt 6.1.

См. также availableBackends(), activeBackend() и isProtocolSupported().

[static] bool QSslSocket::supportsSsl()

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

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

Реализует: QAbstractSocket::waitForBytesWritten(int msecs).

[override virtual] 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).