Класс TLS

Публичные типы

enum	Error { ErrorSignerExpired , ErrorSignerInvalid , ErrorCertKeyMismatch , ErrorInit , ErrorHandshake , ErrorCrypt }
enum	IdentityResult { Valid , HostMismatch , InvalidCertificate , NoCertificate }
enum	Mode { Stream , Datagram }
enum	Version { TLS_v1 , SSL_v3 , SSL_v2 , DTLS_v1 }

Сигналы

void	certificateRequested ()
void	handshaken ()
void	hostNameReceived ()
void	peerCertificateAvailable ()

Сигналы, унаследованные от QCA::SecureLayer

void	closed ()
void	error ()
void	readyRead ()
void	readyRead ()

Публичные функции

int	bytesAvailable () const override
int	bytesOutgoingAvailable () const override
bool	canCompress () const
bool	canSetHostName () const
int	cipherBits () const
int	cipherMaxBits () const
QString	cipherSuite () const
void	close () override
bool	compressionEnabled () const
void	continueAfterStep ()
int	convertBytesWritten (qint64 encryptedBytes) override
Error	errorCode () const
QString	hostName () const
bool	isClosable () const override
bool	isCompressed () const
bool	isHandshaken () const
QList<CertificateInfoOrdered>	issuerList () const
CertificateChain	localCertificateChain () const
PrivateKey	localPrivateKey () const
int	packetMTU () const
int	packetsAvailable () const
int	packetsOutgoingAvailable () const
CertificateChain	peerCertificateChain () const
Validity	peerCertificateValidity () const
IdentityResult	peerIdentityResult () const
QByteArray	read () override
QByteArray	readOutgoing (int *plainBytes=nullptr) override
QByteArray	readUnprocessed () override
void	reset ()
TLSSession	session () const
void	setCertificate (const CertificateChain &cert, const PrivateKey &key)
void	setCertificate (const KeyBundle &kb)
void	setCompressionEnabled (bool b)
void	setConstraints (const QStringList &cipherSuiteList)
void	setConstraints (int minSSF, int maxSSF)
void	setConstraints (SecurityLevel s)
void	setIssuerList (const QList<CertificateInfoOrdered> &issuers)
void	setPacketMTU (int size) const
void	setSession (const TLSSession &session)
void	setTrustedCertificates (const CertificateCollection &trusted)
void	startClient (const QString &host=QString())
void	startServer ()
QStringList	supportedCipherSuites (const Version &version=TLS_v1) const
	TLS (Mode mode, QObject *parent=nullptr, const QString &provider=QString())
	TLS (QObject *parent=nullptr, const QString &provider=QString())
CertificateCollection	trustedCertificates () const
Version	version () const
void	write (const QByteArray &a) override
void	writeIncoming (const QByteArray &a) override
	~TLS () override

Публичные функции, унаследованные от QCA::SecureLayer

SecureLayer (QObject *parent=nullptr)

Публичные функции, унаследованные от QCA::Algorithm

	Algorithm (const Algorithm &from)
void	change (const QString &type, const QString &provider)
void	change (Provider::Context *c)
Provider::Context *	context ()
const Provider::Context *	context () const
Algorithm &	operator= (const Algorithm &from)
Provider *	provider () const
Provider::Context *	takeContext ()
QString	type () const

Защищённые методы

void	connectNotify (const QMetaMethod &signal) override
void	disconnectNotify (const QMetaMethod &signal) override

Защищённые функции, унаследованные от QCA::Algorithm

Algorithm ()

Algorithm (const QString &type, const QString &provider)

Дружественные функции и классы

class

Private

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

Transport Layer Security/Secure Socket Layer.

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

TLS — это стандарт IETF (RFC2712 для TLS версии 1.0 и RFC4346 для TLS версии 1.1), основанный на более ранних работах Netscape по уровню защищённых сокетов (SSL версии 2 и SSL версии 3). Новые приложения должны использовать как минимум TLS 1.0, а SSL версии 2 следует избегать из-за известных проблем с безопасностью.

Примеры

sslservtest.cpp, ssltest.cpp и tlssocket.cpp.

Описание перечислений

Mode

enum QCA::TLS::Mode

Режим работы.

Stream	Потоковый режим
Datagram	Режим датаграммы

Version

enum QCA::TLS::Version

Версия TLS или SSL.

TLS_v1	Transpost Layer Security, версия 1
SSL_v3	Secure Socket Layer, версия 3
SSL_v2	Secure Socket Layer, версия 2
DTLS_v1	Datagram Transport Layer Security, версия 1

Error

enum QCA::TLS::Error

Тип ошибки.

ErrorSignerExpired	Срок действия локального сертификата истёк
ErrorSignerInvalid	Локальный сертификат каким-то образом недействителен
ErrorCertKeyMismatch	Сертификат и закрытый ключ не совпадают
ErrorInit	Проблема с запуском TLS
ErrorHandshake	Проблема во время переговоров
ErrorCrypt	Проблема в любое время после

IdentityResult

enum QCA::TLS::IdentityResult

Тип идентичности.

Valid	Идентичность проверена
HostMismatch	Предоставлен действительный сертификат, но неверно указан владелец
InvalidCertificate	Недействительный сертификат
NoCertificate	Идентичность неизвестна

Описание конструкторов и деструктора

TLS() [1/2]

QCA::TLS::TLS (QObject * parent = nullptr, const QString & provider = QString() )

explicit

Конструктор подключения для протокола безопасности транспортного уровня.

Он создаёт объект Stream (обычный TLS), а не датаграмму (DTLS). Если нужно использовать DTLS, см. ниже.

Параметры

parent	Родительский объект для этого экземпляра
provider	Название криптопровайдера, если требуется конкретный криптопровайдер

TLS() [2/2]

QCA::TLS::TLS (Mode mode, QObject * parent = nullptr, const QString & provider = QString() )

explicit

Конструктор подключения для протокола безопасности транспортного уровня.

Этот конструктор можно использовать как для обычного TLS (установить режим TLS::Stream) , так и для DTLS (установить режим TLS::Datagram).

Параметры

mode	Режим подключения
parent	Родительский объект для этого экземпляра
provider	Название криптопровайдера, если требуется конкретный криптопровайдер

~TLS()

QCA::TLS::~TLS ()

override

Деструктор.

Описание методов

reset()

void QCA::TLS::reset ()

Сбрасывает соединение.

Примеры

tlssocket.cpp.

supportedCipherSuites()

QStringList QCA::TLS::supportedCipherSuites (const Version & version = TLS_v1) const

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

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

Параметры

version

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

Возвращает список названий поддерживаемых наборов шифров.

setCertificate() [1/2]

void QCA::TLS::setCertificate (const CertificateChain & cert, const PrivateKey & key )

Используемый локальный сертификат.

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

Параметры

cert	Цепочка сертификатов, которые связывают сертификат хоста с доверенным корневым сертификатом
key	Закрытый ключ для цепочки сертификатов

setCertificate() [2/2]

void QCA::TLS::setCertificate (const KeyBundle & kb)

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

Параметры

kb	Комплект ключей, содержащий локальный сертификат и связанный с ним закрытый ключ

trustedCertificates()

CertificateCollection QCA::TLS::trustedCertificates () const

Возвращает набор доверенных сертификатов для этого объекта.

setTrustedCertificates()

void QCA::TLS::setTrustedCertificates (const CertificateCollection & trusted)

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

Как правило, это будет набор корневых сертификатов из системы, которые можно получить с помощью QCA::systemStore(), однако можно передать и любые сертификаты, соответствующие потребностям приложения.

Параметры

trusted

Комплект доверенных сертификатов

Примеры

ssltest.cpp и tlssocket.cpp.

setConstraints() [1/3]

void QCA::TLS::setConstraints (SecurityLevel s)

Уровень безопасности, необходимый для этого соединения.

Параметры

s	Уровень, необходимый для этого соединения

setConstraints() [2/3]

void QCA::TLS::setConstraints (int minSSF, int maxSSF )

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

Параметры

minSSF	Минимальный фактор силы безопасности, необходимый для этого соединения
maxSSF	Максимальный фактор силы безопасности, необходимый для этого соединения

setConstraints() [3/3]

void QCA::TLS::setConstraints (const QStringList & cipherSuiteList)

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

Параметры

cipherSuiteList

Список названий комплектов шифров, которые можно использовать для этого соединения.

Примечание.

Названия совпадают с названиями в соответствующих RFC IETF (или в Интернет-проектах, если нет применимого RFC).

issuerList()

QList<CertificateInfoOrdered> QCA::TLS::issuerList () const

Получает список разрешённых издателей на сервере, если сервер их предоставил.

Будут присутствовать только типы DN.

Certificate someCert = ...
PrivateKey someKey = ...
 
// проверяет, примет ли сервер сертификат
CertificateInfoOrdered issuerInfo = someCert.issuerInfoOrdered().dnOnly();
foreach(const CertificateInfoOrdered &info, tls->issuerList())
{
   if(info == issuerInfo)
   {
      // сервер примет someCert, нужно его предоставить
      tls->setCertificate(someCert, someKey);
      break;
   }
}

Примеры

ssltest.cpp.

setIssuerList()

void QCA::TLS::setIssuerList (const QList<CertificateInfoOrdered> & issuers)

Устанавливает список издателей для представления клиенту.

Только для использования с серверами. Разрешены только типы DN.

Параметры

issuers

Список действующих издателей, которые будут использоваться

setSession()

void QCA::TLS::setSession (const TLSSession & session)

Возобновляет сеанс TLS, используя данный объект сеанса.

Параметры

session

Состояние сеанса, используемое для возобновления

canCompress()

bool QCA::TLS::canCompress () const

Проверяет, может ли соединение использовать сжатие.

Возвращает true, если соединение может использовать сжатие.

canSetHostName()

bool QCA::TLS::canSetHostName () const

Проверяет, может ли соединение указывать имя хоста (указание имени сервера).

Возвращает true, если соединение может указывать имя хоста.

compressionEnabled()

bool QCA::TLS::compressionEnabled () const

Возвращает true, если сжатие включено.

Результат указывает только на то, настроен ли объект на использование сжатия, но не на то, действительно ли сжимается соединение. Для такой проверки следует использовать isCompressed().

setCompressionEnabled()

void QCA::TLS::setCompressionEnabled (bool b)

Указывает, использовать ли соединению сжатие.

Параметры

b	True, если соединение должно использовать сжатие, или false, чтобы отключить сжатие

hostName()

QString QCA::TLS::hostName () const

Возвращает указанное имя хоста или пустую строку, если имя хоста не указано.

startClient()

void QCA::TLS::startClient (const QString & host = QString())

Запускает соединение TLS / SSL в качестве клиента.

Как правило, нужно выполнить проверку сертификата сервера RFC 2818 на основе имени хоста, к которому будет подключение. Требуется передать значение host, чтобы получить подтверждение. Если нужно обойти это поведение и выполнить проверку самостоятельно, следует передать пустую строку для host.

Если хост — это интернационализированное доменное имя, то оно должно быть предоставлено в формате Unicode, а не в формате IDNA ACE / Punycode.

Параметры

host	Имя хоста, к которому нужно подключиться

Примечание.

Имя хоста будет использоваться для расширения индикации имени сервера (см. RFC 3546, раздел 3.1), если оно поддерживается внутренним криптопровайдером.

Примеры

ssltest.cpp и tlssocket.cpp.

startServer()

void QCA::TLS::startServer ()

Запускает соединение TLS/SSL в качестве сервера.

continueAfterStep()

void QCA::TLS::continueAfterStep ()

Возобновляет обработку TLS.

Эту функцию следует вызывать после отправки hostNameReceived(), certificateRequested() peerCertificateAvailable() или handshaken(). Требование вызова этой функции для продолжения предоставляет приложениям возможность выполнять взаимодействие с пользователем между этапами процесса TLS.

Примеры

ssltest.cpp.

isHandshaken()

bool QCA::TLS::isHandshaken () const

Проверяет, завершено ли рукопожатие.

Возвращает true, если рукопожатие завершено.

См. также handshaken

isCompressed()

bool QCA::TLS::isCompressed () const

Проверяет, не сжато ли соединение.

Возвращает true, если соединение сжато.

version()

Version QCA::TLS::version () const

Версия протокола, используемая для этого соединения.

cipherSuite()

QString QCA::TLS::cipherSuite () const

Набор шифров, согласованный для этого соединения.

Возвращаемое здесь имя — это имя, используемое в соответствующем RFC (или в Интернет-проекте, где нет RFC).

Примеры

ssltest.cpp.

cipherBits()

int QCA::TLS::cipherBits () const

Количество эффективных битов защиты, используемых для этого соединения.

Оно может отличаться от фактического количества битов в шифровании некоторых старых «экспортных шифров», которые намеренно повреждены. Если эта информация нужна, следует использовать cipherMaxBits().

Примеры

ssltest.cpp.

cipherMaxBits()

int QCA::TLS::cipherMaxBits () const

Количество битов защиты, которое может использовать шифр.

Обычно это то же самое, что и cipherBits(), но может быть больше для старых «экспортных шифров».

Примеры

ssltest.cpp.

session()

TLSSession QCA::TLS::session () const

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

errorCode()

Error QCA::TLS::errorCode () const

Этот метод возвращает тип возникшей ошибки.

Нужно это проверить, только если испускается сигнал error().

Примеры

ssltest.cpp.

peerIdentityResult()

IdentityResult QCA::TLS::peerIdentityResult () const

После завершения подтверждения SSL/TLS этот метод позволяет определить, есть ли на другом конце соединения (если приложение является клиентом, это сервер; если приложение является сервером, то это клиент) действительный участник.

Следует обратить внимание, что безопасность TLS/SSL зависит от этой проверки. Недостаточно проверить действительность сертификата — необходимо убедиться, что сертификат действителен для объекта, с которым приложение пытается связаться.

Примечание.

Если он возвращает QCA::TLS::InvalidCertificate, можно использовать peerCertificateValidity(), чтобы определить, продолжать или нет.

Примеры

ssltest.cpp и tlssocket.cpp.

peerCertificateValidity()

virtual Validity QCA::TLSContext::peerCertificateValidity() const

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

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

Примеры

ssltest.cpp.

localCertificateChain()

CertificateChain QCA::TLS::localCertificateChain () const

CertificateChain для сертификата локального хоста.

localPrivateKey()

PrivateKey QCA::TLS::localPrivateKey () const

PrivateKey для сертификата локального хоста.

peerCertificateChain()

CertificateChain QCA::TLS::peerCertificateChain () const

[CertificateChain](CertificateChain.md) от другого участника соединения с доверенным корневым сертификатом.

Примеры

ssltest.cpp.

isClosable()

bool QCA::TLS::isClosable () const

override virtual

Возвращает true, если слой предоставляет значимую реализацию метода «close».

Переопределено из QCA::SecureLayer.

bytesAvailable()

int QCA::TLS::bytesAvailable () const

override virtual

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

Реализует QCA::SecureLayer.

bytesOutgoingAvailable()

int QCA::TLS::bytesOutgoingAvailable () const

override virtual

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

Реализует QCA::SecureLayer.

close()

void QCA::TLS::close ()

override virtual

Закрывает сетевое соединение.

Следует обратить внимание, что данный метод может не иметь смысла или невозможен для всех реализаций.

См. также Метод isClosable() может быть использован для проверки возможности закрытия сетевого соединения.

Переопределено из QCA::SecureLayer.

write()

void QCA::TLS::write (const QByteArray & a)

override virtual

Метод записывает незашифрованные данные в объект, реализующий интерфейс SecureLayer.

Обычно данный метод вызывается на стороне приложения.

Параметры

a	Источник данных со стороны приложения

Реализует QCA::SecureLayer.

Примеры

ssltest.cpp и tlssocket.cpp.

read()

QByteArray QCA::TLS::read ()

override virtual

Метод считывает расшифрованные данные из объекта, реализующего интерфейс SecureLayer.

Обычно данный метод вызывается на стороне приложения после получения сигнала readyRead().

Реализует QCA::SecureLayer.

Примеры

ssltest.cpp и tlssocket.cpp.

writeIncoming()

void QCA::TLS::writeIncoming (const QByteArray & a)

override virtual

Метод принимает закодированные (обычно зашифрованные) данные для обработки.

Обычно данный метод вызывается после получения информации из сетевого сокета, например, через использование метода QTcpSocket::readAll(). Чтение из сокета осуществляется после получения сигнала о том, что в нём доступны данные для чтения.

Параметры

a	Массив ByteArray, из которого получаются данные со стороны сетевого взаимодействия

Реализует QCA::SecureLayer.

Примеры

ssltest.cpp и tlssocket.cpp.

readOutgoing()

QByteArray QCA::TLS::readOutgoing (int * plainBytes = nullptr)

override virtual

Метод предоставляет закодированные (обычно зашифрованные) данные.

Обычно данный метод вызывается, чтобы получить данные для записи в сетевой сокет, например для передачи в QTcepSocker::write(). Данный метод обычно вызывается после получения сигнала readyReadOutgoing().

Параметры

plainBytes

Количество прочитанных байтов

Реализует QCA::SecureLayer.

Примеры

ssltest.cpp и tlssocket.cpp.

readUnprocessed()

QByteArray QCA::TLS::readUnprocessed ()

override virtual

Метод позволяет считывать данные без выполнения дешифрования.

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

Переопределено из QCA::SecureLayer.

convertBytesWritten()

int QCA::TLS::convertBytesWritten (qint64encryptedBytes)

override virtual

Преобразует уже записанные зашифрованные байты в байты простого текста.

Параметры

encryptedBytes

Количество байтов для преобразования

Реализует QCA::SecureLayer.

packetsAvailable()

int QCA::TLS::packetsAvailable () const

Определяет количество пакетов, доступных для чтения на стороне приложения.

Примечание.

Метод используется только с DTLS.

packetsOutgoingAvailable()

int QCA::TLS::packetsOutgoingAvailable () const

Определяет количество пакетов, доступных для чтения на стороне сети.

Примечание.

Метод используется только с DTLS.

packetMTU()

int QCA::TLS::packetMTU () const

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

Примечание.

Это используется только с DTLS.

setPacketMTU()

void QCA::TLS::setPacketMTU (int size) const

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

Параметры

size	Количество байтов, устанавливаемое как MTU

Примечание.

Метод используется только с DTLS.

hostNameReceived

void QCA::TLS::hostNameReceived ()

signal

Сигнал испускается, если имя хоста задано клиентом.

В это время сервер может проверить hostName().

Нужно вызвать continueAfterStep(), чтобы обработка TLS возобновилась после передачи этого сигнала.

Этот сигнал испускается только в серверном режиме.

См. также continueAfterStep

certificateRequested

void QCA::TLS::certificateRequested ()

signal

Сигнал испускается, когда сервер запрашивает сертификат.

В это время клиент может проверить issuerList().

Нужно вызвать continueAfterStep(), чтобы обработка TLS возобновилась после передачи этого сигнала.

Этот сигнал испускается только в клиентском режиме.

См. также continueAfterStep

Примеры

ssltest.cpp.

peerCertificateAvailable

void QCA::TLS::peerCertificateAvailable ()

signal

Сигнал испускается, когда сертификат получен от другого участника соединения.

CertificateChain от другого участника соединения с доверенным корневым сертификатом.

Нужно вызвать continueAfterStep(), чтобы обработка TLS возобновилась после передачи этого сигнала.

См. также continueAfterStep

handshaken

void QCA::TLS::handshaken ()

signal

Сигнал испускается, когда подтверждение протокола завершено.

В это время можно просмотреть всю доступную информацию о сеансе TLS.

Нужно вызвать continueAfterStep(), чтобы обработка TLS возобновилась после передачи этого сигнала.

См. также continueAfterStep

isHandshaken

Примеры

sslservtest.cpp, ssltest.cpp и tlssocket.cpp.

connectNotify()

void QCA::TLS::connectNotify (const QMetaMethod & signal)

override protected

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

Параметры

signal

Имя сигнала, к которому идёт подключение

disconnectNotify()

void QCA::TLS::disconnectNotify (const QMetaMethod & signal)

override protected

Вызывается, когда от определённого сигнала удаляется соединение.

Параметры

signal

Имя сигнала, от которого идёт отключение