Функция EncryptMessage (sspi.h)

Статья
08/26/2023

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

Эта функция доступна только в виде механизма SASL.

Примечание. EncryptMessage (Digest) и DecryptMessage (Digest) можно вызывать одновременно из двух разных потоков в одном контексте SSPI , если один поток шифруется, а другой расшифровывается. Если шифруется несколько потоков или расшифровывается несколько потоков, каждый поток должен получить уникальный контекст.

Синтаксис

SECURITY_STATUS SEC_ENTRY EncryptMessage(
  [in]      PCtxtHandle    phContext,
  [in]      unsigned long  fQOP,
  [in, out] PSecBufferDesc pMessage,
  [in]      unsigned long  MessageSeqNo
);

Параметры

[in] phContext

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

[in] fQOP

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

При использовании дайджест-поставщика общих служб этот параметр должен иметь нулевое значение.

[in, out] pMessage

Указатель на структуру SecBufferDesc . Во входных данных структура ссылается на одну или несколько структур SecBuffer , которые могут иметь тип SECBUFFER_DATA. Этот буфер содержит зашифрованное сообщение. Сообщение шифруется на месте, перезаписывается исходное содержимое структуры.

Функция не обрабатывает буферы с помощью атрибута SECBUFFER_READONLY.

Длина структуры SecBuffer , содержащей сообщение, не должна превышать cbMaximumMessage, полученную из функции QueryContextAttributes (Digest) (SECPKG_ATTR_STREAM_SIZES).

При использовании дайджест-поставщика общих служб для хранения сведений о сигнатуре должен быть второй буфер типа SECBUFFER_PADDING или SEC_BUFFER_DATA. Чтобы получить размер выходного буфера, вызовите функцию QueryContextAttributes (Digest) и укажите SECPKG_ATTR_SIZES. Функция вернет структуру SecPkgContext_Sizes . Размер выходного буфера — это сумма значений в членах cbMaxSignature и cbBlockSize .

Приложения, которые не используют SSL, должны предоставлять SecBuffer типа SECBUFFER_PADDING.

[in] MessageSeqNo

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

При использовании дайджест-поставщика общих служб этот параметр должен иметь нулевое значение. Дайджест SSP управляет порядковой нумеровой службой внутри системы.

Возвращаемое значение

Если функция выполняется успешно, функция возвращает SEC_E_OK.

Если функция завершается сбоем, она возвращает один из следующих кодов ошибок.

Код возврата	Описание
SEC_E_BUFFER_TOO_SMALL	Выходной буфер слишком мал. Дополнительные сведения см. в подразделе "Примечания".
SEC_E_CONTEXT_EXPIRED	Приложение ссылается на контекст, который уже был закрыт. Правильно написанное приложение не должно получать эту ошибку.
SEC_E_CRYPTO_SYSTEM_INVALID	Шифр, выбранный для контекста безопасности, не поддерживается.
SEC_E_INSUFFICIENT_MEMORY	Недостаточно памяти для выполнения запрошенного действия.
SEC_E_INVALID_HANDLE	Недопустимый дескриптор контекста был указан в параметре phContext .
SEC_E_INVALID_TOKEN	Буфер типа SECBUFFER_DATA не найден.
SEC_E_QOP_NOT_SUPPORTED	Контекст безопасности не поддерживает ни конфиденциальность, ни целостность.

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

При использовании дайджест-поставщика общих служб получите размер выходного буфера, вызвав функцию QueryContextAttributes (Digest) и указав SECPKG_ATTR_SIZES. Функция вернет структуру SecPkgContext_Sizes . Размер выходного буфера — это сумма значений в членах cbMaxSignature и cbBlockSize .

Примечание Эти буферы должны быть предоставлены в указанном порядке.

Тип буфера	Описание
SECBUFFER_STREAM_HEADER	Для внутреннего использования. Инициализация не требуется.
SECBUFFER_DATA	Содержит зашифрованное сообщение в виде открытого текста .
SECBUFFER_STREAM_TRAILER	Для внутреннего использования. Инициализация не требуется.
SECBUFFER_EMPTY	Для внутреннего использования. Инициализация не требуется. Размер может быть равен нулю.

Для оптимальной производительности структуры pMessage должны быть выделены из непрерывной памяти.

Windows XP: Эта функция также известна как SealMessage. Теперь приложения должны использовать только EncryptMessage (Digest).

Требования


Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	sspi.h (включая Security.h)
Библиотека	Secur32.lib
DLL	Secur32.dll