Класс QSslSocket

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

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

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

Типы

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

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

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

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

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

Сигналы

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

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

• 11 статических публичных членов, унаследованных от 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.

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

enum QSslSocket::PeerVerifyMode

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

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

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

enum QSslSocket::SslMode

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

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

QSslSocket::QSslSocket(QObject *parent = Q_NULLPTR)

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

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)

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

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

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

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

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

Добавляет 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)

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

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

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

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

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

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

[virtual] bool QSslSocket::atEnd() const

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

[virtual] qint64 QSslSocket::bytesAvailable() const

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

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

[virtual] qint64 QSslSocket::bytesToWrite() const

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

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

[virtual] bool QSslSocket::canReadLine() const

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

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

[virtual] void QSslSocket::close()

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

void QSslSocket::connectToHostEncrypted(const QString &hostName, quint16 port, OpenMode mode = ReadWrite, 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, OpenMode mode = ReadWrite, 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 игнорировать ошибки во время фазы рукопожатия 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().

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

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

Переопределено из QIODevice::readData().

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

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

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

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

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

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

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

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

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

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

[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. Эта функция устанавливает локальный сертификат, шифры, секретный ключ и сертификаты ЦС на те, которые хранятся в configuration.

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

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

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

[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-handshake для серверного подключения. Данная функция может быть вызвана, когда сокет находится в состоянии ConnectedState, но всё ещё в UnencryptedMode. Если сокет не подключен или уже зашифрован, функция не оказывает никакого эффекта.

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

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

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

[static] bool QSslSocket::supportsSsl()

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

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

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

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

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

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

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

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

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

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

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

bool QSslSocket::waitForEncrypted(int msecs = 30000)

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

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

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

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

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

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

Переопределено из QIODevice::waitForReadyRead().

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

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