Класс SecureMessage

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

enum	Error { ErrorPassphrase , ErrorFormat , ErrorSignerExpired , ErrorSignerInvalid , ErrorEncryptExpired , ErrorEncryptUntrusted , ErrorEncryptInvalid , ErrorNeedCard , ErrorCertKeyMismatch , ErrorUnknown , ErrorSignerRevoked , ErrorSignatureExpired , ErrorEncryptRevoked }
enum	Format { Binary , Ascii }
enum	SignMode { Message , Clearsign , Detached }
enum	Type { OpenPGP , CMS }

Сигналы

void	bytesWritten (int bytes)
void	finished ()
void	readyRead ()

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

bool	bundleSignerEnabled () const
int	bytesAvailable () const
bool	canClearsign () const
bool	canSignAndEncrypt () const
bool	canSignMultiple () const
QString	diagnosticText () const
void	end ()
Error	errorCode () const
Format	format () const
QString	hashName () const
QByteArray	read ()
SecureMessageKeyList	recipientKeys () const
void	reset ()
	SecureMessage (SecureMessageSystem *system)
void	setBundleSignerEnabled (bool b)
void	setFormat (Format f)
void	setRecipient (const SecureMessageKey &key)
void	setRecipients (const SecureMessageKeyList &keys)
void	setSigner (const SecureMessageKey &key)
void	setSigners (const SecureMessageKeyList &keys)
void	setSMIMEAttributesEnabled (bool b)
QByteArray	signature () const
SecureMessageSignature	signer () const
SecureMessageKeyList	signerKeys () const
SecureMessageSignatureList	signers () const
bool	smimeAttributesEnabled () const
void	startDecrypt ()
void	startEncrypt ()
void	startSign (SignMode m=Message)
void	startSignAndEncrypt ()
void	startVerify (const QByteArray &detachedSig=QByteArray())
bool	success () const
Type	type () const
void	update (const QByteArray &in)
bool	verifySuccess () const
bool	waitForFinished (int msecs=30000)
bool	wasSigned () const

Публичные функции, унаследованные от 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

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

class

Private

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

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

Algorithm ()

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

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

Класс, представляющий защищённое сообщение.

SecureMessage представляет собой единый интерфейс для работы с сообщениями OpenPGP и CMS (S/MIME). Объект можно подготовить, вызвав setFormat(), setRecipient() и setSigner() по мере необходимости, а затем начать операцию, вызвав соответствующую функцию «start», например startSign().

Пример того, как выполнить операцию Clearsign с помощью PGP:

// сначала приобретается SecureMessageKey
PGPKey myPGPKey = getSecretKeyFromSomewhere();
SecureMessageKey key;
key.setPGPSecretKey(myPGPKey);
 
// данные для подписи
QByteArray plain = "Hello, world";
 
// основное действие
OpenPGP pgp;
SecureMessage msg(&pgp);
msg.setSigner(key);
msg.startSign(SecureMessage::Clearsign);
msg.update(plain);
msg.end();
msg.waitForFinished(-1);
 
if(msg.success())
{
   QByteArray result = msg.read();
   // результат теперь содержит очищенные и подписанные текстовые данные
}
else
{
   // ошибка
…
}

Выполнение операции знака CMS аналогично. Просто нужно настроить SecureMessageKey с Certificate вместо PGPKey и работать с объектом CMS вместо объекта OpenPGP.

См. также SecureMessageKey

SecureMessageSignature

OpenPGP

CMS

Примеры

publickeyexample.cpp.

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

Type

enum QCA::SecureMessage::Type

Тип защищённого сообщения.

OpenPGP	Достаточно защищённое конфиденциальное сообщение
CMS	Сообщение с криптографическим синтаксисом

SignMode

enum QCA::SecureMessage::SignMode

Тип подписи сообщения.

Message	Сообщение включает подпись
Clearsign	Сообщение подписано чисто
Detached	Подпись отделяется

Format

enum QCA::SecureMessage::Format

Форматы защищённых сообщений.

Binary	DER/бинарное.
Ascii	PEM/ASCII

Error

enum QCA::SecureMessage::Error

Ошибки для защищённых сообщений.

ErrorPassphrase	Кодовая фраза неверна или не указана
ErrorFormat	Формат ввода был недействительным
ErrorSignerExpired	Срок действия ключа подписи истёк
ErrorSignerInvalid	Ключ подписи каким-то образом недействителен
ErrorEncryptExpired	Срок действия ключа шифрования истёк
ErrorEncryptUntrusted	Ключ шифрования ненадёжный
ErrorEncryptInvalid	Ключ шифрования каким-то образом недействителен
ErrorNeedCard	Отсутствует карта pgp
ErrorCertKeyMismatch	Сертификат и закрытый ключ не совпадают
ErrorUnknown	Другая ошибка
ErrorSignerRevoked	Ключ подписи отозван
ErrorSignatureExpired	Срок действия подписи истёк
ErrorEncryptRevoked	Ключ шифрования отозван

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

SecureMessage()

QCA::SecureMessage::SecureMessage (SecureMessageSystem * system)

Создёт новое защищённое сообщение.

Конструктор использует существующий объект SecureMessageSystem (например, объект OpenPGP или CMS) для создания определённого типа защищённого сообщения.

Параметры

system

Уже существующий и настроенный объект SecureMessageSystem

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

type()

Type QCA::SecureMessage::type () const

Тип защищённого сообщения.

canSignMultiple()

bool QCA::SecureMessage::canSignMultiple () const

Проверяет, поддерживает ли тип сообщения несколько (параллельных) подписей.

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

Примечание.

PGP не поддерживает параллельные подписи — это в первую очередь функциональность CMS.

canClearsign()

bool QCA::SecureMessage::canClearsign () const

True, если SecureMessageSystem может очищать и подписывать сообщения.

Примечание.

CMS не может очистить и подписать сообщение — обычно это доступно только для PGP.

canSignAndEncrypt()

bool QCA::SecureMessage::canSignAndEncrypt () const

True, если SecureMessageSystem может подписывать и шифровать (за одну операцию).

Примечание.

CMS не может выполнять объединённые подпись и шифрование — обычно это доступно только для PGP. Тем не менее можно выполнять отдельные операции подписи и шифрования для одного и того же сообщения с помощью CMS.

reset()

void QCA::SecureMessage::reset ()

Сбрасывает объект в исходное состояние.

Теперь можно сразу приступить к новой операции.

bundleSignerEnabled()

bool QCA::SecureMessage::bundleSignerEnabled () const

Возвращает true, если включено объединение цепочки подписывающих сертификатов.

smimeAttributesEnabled()

bool QCA::SecureMessage::smimeAttributesEnabled () const

Возвращает true, если доступно присоединение атрибутов S/MIME.

format()

Format QCA::SecureMessage::format () const

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

recipientKeys()

SecureMessageKeyList QCA::SecureMessage::recipientKeys () const

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

signerKeys()

SecureMessageKeyList QCA::SecureMessage::signerKeys () const

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

setBundleSignerEnabled()

void QCA::SecureMessage::setBundleSignerEnabled (bool b)

Только для CMS: цепочка сертификатов подписывающей стороны будет включена в сообщение.

Метод позволяет проверять сообщение самостоятельно, без предварительного получения сертификата подписывающей стороны. Клиенты электронной почты, использующие S/MIME, часто объединяют подписывающих, что значительно упрощает управление ключами.

Такое поведение включено по умолчанию.

Параметры

b	Объединять (если true) или нет (false)

setSMIMEAttributesEnabled()

void QCA::SecureMessage::setSMIMEAttributesEnabled (bool b)

Только для CMS: в сообщение будут добавлены дополнительные атрибуты, связанные с S/MIME, такие как предпочтительный тип алгоритма для использования в ответах.

Используемые атрибуты определяются криптопровайдером.

Такое поведение включено по умолчанию.

Параметры

b	Следует ли вставлять дополнительные атрибуты (если true) или нет (false)

setFormat()

void QCA::SecureMessage::setFormat (Format f)

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

По умолчанию Binary.

Параметры

f	Использовать Binary или ASCII

setRecipient()

void QCA::SecureMessage::setRecipient (const SecureMessageKey & key)

Устанавливает получателя зашифрованного сообщения.

Параметры

key	Ключ получателя.

См. также setRecipients.

Примеры

publickeyexample.cpp.

setRecipients()

void QCA::SecureMessage::setRecipients (const SecureMessageKeyList & keys)

Устанавливает список получателей зашифрованного сообщения.

Для списка с одним элементом метод выполняет то же, что и setRecipient.

Параметры

keys	Ключ получателей

См. также setRecipient.

setSigner()

void QCA::SecureMessage::setSigner (const SecureMessageKey & key)

Устанавливает автора подписи для подписанного сообщения.

Метод используется как для создания подписанных сообщений, так и для проверки сообщений CMS, у которых нет автора подписи.

Параметры

key	Ключ, связанный с автором подписи

См. также setSigners

setSigners()

void QCA::SecureMessage::setSigners (const SecureMessageKeyList & keys)

Устанавливает список авторов подписей для подписанного сообщения.

Метод используется как для создания подписанных сообщений, так и для проверки сообщений CMS, у которых нет автора подписи.

Для списка с одним элементом метод выполняет то же, что и setSigner.

Параметры

keys	Ключ, связанный с автором подписи

См. также setSigner.

startEncrypt()

void QCA::SecureMessage::startEncrypt ()

Запускает операцию шифрования.

Обычно метод будет использоваться с кодом, подобным следующему:

encryptingObj.startEncrypt();
encryptingObj.update(message);
// возможно, ещё несколько update()
encryptingObj.end();

Результатом каждого update() могут быть (или не быть) некоторые зашифрованные данные, на что указывает испускаемый сигнал readyRead(). В качестве альтернативы можно подождать, пока всё сообщение не станет доступным, используя waitForFinished() или сигнал finished(). Затем зашифрованное сообщение можно прочитать с помощью метода read().

Примеры

publickeyexample.cpp.

startDecrypt()

void QCA::SecureMessage::startDecrypt ()

Запускает операцию дешифрования.

Обычно метод будет использоваться с кодом, подобным следующему:

decryptingObj.startEncrypt();
decryptingObj.update(message);
// возможно, ещё несколько update()
decryptingObj.end();

Результатом каждого update() могут быть (или не быть) некоторые дешифрованные данные, на что указывает испускаемый сигнал readyRead(). В качестве альтернативы можно подождать, пока всё сообщение не станет доступным, используя waitForFinished() или сигнал finished(). Затем расшифрованное сообщение можно прочитать с помощью метода read().

Примечание.

Если расшифрованный результат также подписан (не для CMS), то подпись будет проверена во время этой операции.

startSign()

void QCA::SecureMessage::startSign (SignMode m = Message)

Запускает операцию подписи.

Обычно метод будет использоваться с кодом, подобным следующему:

signingObj.startSign(QCA::SecureMessage::Detached)
signingObj.update(message);
// возможно, ещё несколько update()
signingObj.end();

Для отсоединённых подписей никакие результаты не вернутся, пока весь процесс не будет завершён. Нужно использовать или waitForFinished(), или finished(), чтобы выяснить, когда можно получить подпись (используя метод signature(), а не read()). Для других форматов можно использовать сигнал readyRead(), чтобы определить, когда может быть получена часть подписанного сообщения для read().

Параметры

m	Режим, который будет использоваться для генерации подписи

startVerify()

void QCA::SecureMessage::startVerify (const QByteArray & detachedSig = QByteArray())

Запускает операцию проверки.

Параметры

detachedSig

Отсоединённая подпись для проверки. Не следует передавать подпись для других типов подписей.

startSignAndEncrypt()

void QCA::SecureMessage::startSignAndEncrypt ()

Запускает комбинированную операцию подписи и шифрования.

Метод используется так же, как и startEncrypt().

Примечание.

Такая функциональность может быть недоступна (например, CMS не может этого сделать). См. canSignAndEncrypt() для соответствующей проверки.

update()

void QCA::SecureMessage::update (const QByteArray & in)

Обрабатывает сообщение (или следующую часть сообщения) в текущей операции.

Перед вызовом этого метода необходимо настроить сообщение (startEncrypt(), startDecrypt(), startSign(), startSignAndEncrypt() и startVerify()).

Параметры

in	Данные для обработки

Примеры

publickeyexample.cpp.

read()

QByteArray QCA::SecureMessage::read ()

Читает доступные данные.

Примечание.

Для отсоединённых подписей с помощью этого метода ничего не вернётся обратно. Следует использовать signature(), чтобы получить отсоединённую signature().

Примеры

publickeyexample.cpp.

bytesAvailable()

int QCA::SecureMessage::bytesAvailable () const

Количество байтов, доступных для чтения.

end()

void QCA::SecureMessage::end ()

Завершает операцию.

Необходимо вызвать этот метод после обработки сообщения, которое передаётся в качестве аргумента update().

Примечание.

результаты операции недоступны, пока метод не вернулся. Нужно дождаться сигнала finished() или должаться waitForFinished().

Примеры

publickeyexample.cpp.

waitForFinished()

bool QCA::SecureMessage::waitForFinished (int msecs = 30000)

Блокируется до завершения операции (шифрование, дешифрование, подпись или проверка).

Параметры

msecs

Cколько ждать миллисекунд до завершения операции. Следует передать -1, чтобы ждать бесконечно

Примечание.

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

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

Примеры

publickeyexample.cpp.

success()

bool QCA::SecureMessage::success () const

Указывает, была ли операция успешной или неудачной.

Если эта функция возвращает false, то причину сбоя можно узнать с помощью errorCode().

См. также errorCode

diagnosticText

Примеры

publickeyexample.cpp.

errorCode()

Error QCA::SecureMessage::errorCode () const

Возвращает код ошибки.

См. также success

diagnosticText

Примеры

publickeyexample.cpp.

signature()

QByteArray QCA::SecureMessage::signature () const

Подпись сообщения.

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

hashName()

QString QCA::SecureMessage::hashName () const

Название хеша, используемого для процесса подписи.

wasSigned()

bool QCA::SecureMessage::wasSigned () const

Проверяет, было ли сообщение подписано.

Результат равен true для OpenPGP, если расшифрованное сообщение также было подписано.

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

verifySuccess()

bool QCA::SecureMessage::verifySuccess () const

Проверяет правильность подписи сообщения.

Возвращает true, если подпись действительна для сообщения, иначе false.

signer()

SecureMessageSignature QCA::SecureMessage::signer () const

Информация об авторе подписи для сообщения.

signers()

SecureMessageSignatureList QCA::SecureMessage::signers () const

Информация об авторах подписи для сообщения.

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

diagnosticText()

QString QCA::SecureMessage::diagnosticText () const

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

readyRead

void QCA::SecureMessage::readyRead ()

signal

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

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

Примечание.

Этот сигнал не означает, что обработка сообщения обязательно завершена — см. finished().

bytesWritten

void QCA::SecureMessage::bytesWritten (int bytes)

signal

Сигнал испускается, когда данные были приняты обработчиком сообщений.

Параметры

bytes

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

finished

void QCA::SecureMessage::finished ()

signal

Сигнал испускается, когда сообщение полностью обработано.