Класс QSslSocket

Класс QSslSocket предоставляет SSL-защищённый сокет для клиентов и серверов. Подробнее...

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

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

Открытые типы

Открытые функции

Переопределённые открытые функции

• 37 общедоступных функций, унаследованных от QAbstractSocket
• 44 общедоступных функций, унаследованных от QIODevice
• 31 общедоступных функций, унаследованных от QObject

Публичные слоты

• 1 публичный слот, унаследованный от QObject

Сигналы

• 6 сигналов, унаследованных от QAbstractSocket
• 6 сигналов, унаследованных от QIODevice
• 2 сигнала, унаследованных от QObject

Статические общедоступные члены

• 9 статических общедоступных членов, унаследованных от QObject

Переопределённые защищённые функции

• 10 защищённых функций, унаследованных от QAbstractSocket
• 5 защищённых функций, унаследованных от QIODevice
• 9 защищённых функций, унаследованных от QObject

Дополнительные унаследованные члены

• 1 свойство, унаследованное от QObject
• 10 защищённых функций, унаследованных от QAbstractSocket
• 5 защищённых функций, унаследованных от QIODevice
• 9 защищённых функций, унаследованных от QObject

Подробное описание

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

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 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 для обработки ошибок, возникающих во время фазы рукопожатия.

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

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

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

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

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

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

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

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

перечисление QSslSocket::PeerVerifyMode

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

Это перечисление было добавлено или изменено в Qt 4.4.

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

перечисление QSslSocket::SslMode

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

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

QSslSocket::QSslSocket(QObject *parent = nullptr)

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

[virtual] QSslSocket::~QSslSocket()

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

void QSslSocket::abort()

Прерывает текущее соединение и сбрасывает сокет. В отличие от disconnectFromHost(), эта функция немедленно закрывает сокет, очищая любые ожидающие данные в буфере записи.

См. также disconnectFromHost() и close().

void QSslSocket::addCaCertificate(const QSslCertificate &certificate)

Добавляет certificate в базу данных сертификатов CA этого сокета. База данных сертификатов CA используется сокетом во время фазы рукопожатия для проверки сертификата удалённой стороны.

Для добавления нескольких сертификатов используйте addCaCertificates().

См. также caCertificates() и setCaCertificates().

bool QSslSocket::addCaCertificates(const QString &path, QSsl::EncodingFormat format = QSsl::Pem, QRegExp::PatternSyntax syntax = QRegExp::FixedString)

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

База данных сертификатов доверенных центров выдачи используется сокетом на стадии установления соединения для проверки сертификата удалённого узла.

Для более точного управления используйте addCaCertificate().

См. также addCaCertificate() и QSslCertificate::fromPath().

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

Добавляет сертификаты в базу данных сертификатов доверенных центров выдачи этого сокета. База данных сертификатов доверенных центров выдачи используется сокетом на стадии установления соединения для проверки сертификата удалённого узла.

Для более точного управления используйте addCaCertificate().

См. также caCertificates() и addDefaultCaCertificate().

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

Добавляет certificate в базу данных сертификатов по умолчанию доверенных центров выдачи. База данных сертификатов доверенных центров выдачи каждого сокета SSL инициализируется по умолчанию.

См. также defaultCaCertificates() и addCaCertificates().

[static] bool QSslSocket::addDefaultCaCertificates(const QString &path, QSsl::EncodingFormat encoding = QSsl::Pem, QRegExp::PatternSyntax syntax = QRegExp::FixedString)

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

База данных сертификатов доверенных центров выдачи каждого сокета SSL инициализируется по умолчанию.

См. также defaultCaCertificates(), addCaCertificates() и addDefaultCaCertificate().

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

Добавляет certificates в базу данных сертификатов по умолчанию доверенных центров выдачи. База данных сертификатов доверенных центров выдачи каждого сокета SSL инициализируется по умолчанию.

См. также defaultCaCertificates() и addCaCertificates().

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

Переопределено из QAbstractSocket::atEnd().

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

Переопределено из QAbstractSocket::bytesAvailable().

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

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

Переопределено из QAbstractSocket::bytesToWrite().

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

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

Переопределено из QAbstractSocket::canReadLine().

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

[override virtual] void QSslSocket::close()

Переопределено из QAbstractSocket::close().

void QSslSocket::connectToHostEncrypted(const QString &hostName, quint16 port, QIODevice::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, QIODevice::OpenMode mode = ReadWrite, QAbstractSocket::NetworkLayerProtocol protocol = AnyIPProtocol)

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

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

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

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

[signal] void QSslSocket::encrypted()

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

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

qint64 QSslSocket::encryptedBytesAvailable() const

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

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

qint64 QSslSocket::encryptedBytesToWrite() const

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

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

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

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

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

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

bool QSslSocket::flush()

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

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

См. также write() и waitForBytesWritten().

[slot] void QSslSocket::ignoreSslErrors()

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

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

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

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

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);

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

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

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

bool QSslSocket::isEncrypted() const

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

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

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

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

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

QSslCertificate QSslSocket::localCertificate() const

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

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

QList<QSslCertificate> QSslSocket::localCertificateChain() const

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

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

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

QSslSocket::SslMode QSslSocket::mode() const

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

При изменении режима QSslSocket отправляет modeChanged().

См. также SslMode.

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

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

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

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 (по умолчанию), если максимальная глубина не установлена, что указывает на то, что должна быть проверена вся цепочка сертификатов.

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

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

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

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

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

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

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

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

QSslSocket::PeerVerifyMode QSslSocket::peerVerifyMode() const

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

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

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

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

QString QSslSocket::peerVerifyName() const

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

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

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

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

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

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

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

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

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

См. также QSslPreSharedKeyAuthenticator.

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

[override virtual] void QSslSocket::resume()

Переопределено из QAbstractSocket::resume().

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

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

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

QSslCipher QSslSocket::sessionCipher() const

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

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

См. также ciphers(), setCiphers(), setDefaultCiphers(), defaultCiphers() и supportedCiphers().

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.

void QSslSocket::setLocalCertificateChain(const QList<QSslCertificate> &localChain)

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

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

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

void QSslSocket::setPeerVerifyDepth(int depth)

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

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

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

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

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

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

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

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

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

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

void QSslSocket::setPeerVerifyName(const QString &hostName)

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

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

См. также 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().

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

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

[override virtual] bool QSslSocket::setSocketDescriptor(qintptr socketDescriptor, QAbstractSocket::SocketState state = ConnectedState, QIODevice::OpenMode openMode = ReadWrite)

Переопределено из QAbstractSocket::setSocketDescriptor().

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

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

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

[override virtual] void QSslSocket::setSocketOption(QAbstractSocket::SocketOption option, const QVariant &value)

Переопределено из QAbstractSocket::setSocketOption().

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

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

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

void QSslSocket::setSslConfiguration(const QSslConfiguration &configuration)

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

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

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

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

[override virtual] QVariant QSslSocket::socketOption(QAbstractSocket::SocketOption option)

Переопределено из QAbstractSocket::socketOption().

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

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

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

QSslConfiguration QSslSocket::sslConfiguration() const

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

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

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

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

QList<QSslError> QSslSocket::sslErrors() const

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

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

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

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

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

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

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

Примечание: Сигнал sslErrors перегружен в этом классе. Для подключения к этому сигналу с использованием синтаксиса указателя функции Qt предоставляет удобный помощник для получения указателя функции, как показано в этом примере:

connect(sslSocket, QOverload<const QList<QSslError> &>::of(&QSslSocket::sslErrors),
    [=](const QList<QSslError> &errors){ /* ... */ });

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

[static] long QSslSocket::sslLibraryBuildVersionNumber()

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

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

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

[static] QString QSslSocket::sslLibraryBuildVersionString()

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

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

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

[static] long QSslSocket::sslLibraryVersionNumber()

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

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

[static] QString QSslSocket::sslLibraryVersionString()

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

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

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

[static] bool QSslSocket::supportsSsl()

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

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

Переопределено из QAbstractSocket::waitForBytesWritten().

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

Переопределено из QAbstractSocket::waitForConnected().

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

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

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

Переопределено из QAbstractSocket::waitForDisconnected().

Ожидает, пока сокет не будет отключен или не пройдёт 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().

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

Переопределено из QAbstractSocket::writeData().