Класс QSslSocket

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

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

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

Типы публичного доступа

Функции публичного доступа

Реализованные публичные функции

• 37 public functions inherited from QAbstractSocket
• 47 public functions inherited from QIODevice
• 34 public functions inherited from QObject

Public Slots

• 1 public slot inherited from QObject

Сигналы

• 6 signals inherited from QAbstractSocket
• 6 signals inherited from QIODevice
• 2 signals inherited from QObject

Статические public члены

• 2 static public members inherited from QIODevice
• 10 static public members inherited from QObject

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

• 10 protected functions inherited from QAbstractSocket
• 5 protected functions inherited from QIODevice
• 9 protected functions inherited from QObject

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

• 1 property inherited from QObject
• 1 public variable inherited from QIODevice
• 1 public variable inherited from QObject
• 10 protected functions inherited from QAbstractSocket
• 5 protected functions inherited from QIODevice
• 9 protected functions inherited from QObject
• 2 protected variables inherited from 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-рукопожатие после установления соединения.

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

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

• Криптографический набор шифров сокета можно настроить перед фазой рукопожатия с помощью setCiphers() и setDefaultCiphers().
• Локальный сертификат и закрытый ключ сокета можно настроить перед фазой рукопожатия с помощью setLocalCertificate() и setPrivateKey().
• Базу данных сертификатов УЦ можно расширить и настроить с помощью 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.

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

enum QSslSocket::PeerVerifyMode

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

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

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

enum 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 в базу данных сертификатов УЦ этого сокета. База данных сертификатов УЦ используется сокетом во время фазы рукопожатия для проверки сертификата партнёра.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

QList<QSslCertificate> QSslSocket::localCertificateChain() const

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

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

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

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

void QSslSocket::setReadBufferSize(qint64 size)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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.

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