Функция EncryptMessage (General)

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

При использовании поставщика поддержки безопасности digest (SSP) эта функция доступна только как механизм SASL.

При использовании Schannel SSP эта функция шифрует сообщения с помощью сеансового ключа , согласованного с удаленной стороной, которая получит сообщение. Алгоритм шифрования определяется используемым [набором шифров ](cipher-suites-in-schannel.md).

Примечание

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

Сведения об использовании этой функции с определенным поставщиком общих служб см. в следующих разделах.

Раздел	Описание
EncryptMessage (дайджест)	Шифрует сообщение для обеспечения конфиденциальности с помощью дайджеста.
EncryptMessage (Kerberos)	Шифрует сообщение для обеспечения конфиденциальности с помощью Kerberos.
EncryptMessage (Согласование)	Шифрует сообщение для обеспечения конфиденциальности с помощью negotiate.
EncryptMessage (NTLM)	Шифрует сообщение для обеспечения конфиденциальности с помощью NTLM.
EncryptMessage (Schannel)	Шифрует сообщение для обеспечения конфиденциальности с помощью Schannel.

Синтаксис

SECURITY_STATUS SEC_Entry EncryptMessage(
  _In_    PCtxtHandle    phContext,
  _In_    ULONG          fQOP,
  _Inout_ PSecBufferDesc pMessage,
  _In_    ULONG          MessageSeqNo
);

Параметры

phContext [in]

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

fQOP [in]

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

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

Этот параметр может быть одним из следующих флагов.

Значение	Значение
SECQOP_WRAP_NO_ENCRYPT	Создайте заголовок или трейлер, но не шифруйте сообщение. Примечание: KERB_WRAP_NO_ENCRYPT имеет то же значение и одинаковое значение.
SECQOP_WRAP_OOB_DATA	Отправка оповещения Schannel. В этом случае параметр pMessage должен содержать стандартный двухбайтовой код события SSL/TLS. Это значение поддерживается только поставщиком Schannel SSP.

pMessage [вход, выход]

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

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

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

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

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

MessageSeqNo [in]

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

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

При использовании Schannel SSP этому параметру необходимо задать нулевое значение. Поставщик Schannel 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	Контекст безопасности не поддерживает ни конфиденциальность, ни целостность.

Комментарии

Функция EncryptMessage (General) шифрует сообщение на основе сообщения и ключа сеанса из контекста безопасности.

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

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

При использовании с Schannel SSP параметр pMessage должен содержать структуру SecBufferDesc со следующими буферами.

Примечание

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

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

При использовании Schannel SSP определите максимальный размер каждого буфера, вызвав функцию QueryContextAttributes (General) и указав атрибут SECPKG_ATTR_STREAM_SIZES. Эта функция возвращает SecPkgContext_StreamSizes структуру, члены которой содержат максимальные размеры для буферов заголовка (член cbHeader ), сообщения (элемент cbMaximumMessage ) и прицепа (член cbTrailer ).

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

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

Требования

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

См. также раздел

• Функции SSPI
• AcceptSecurityContext (General)
• DecryptMessage (общие)
• InitializeSecurityContext (General)
• QueryContextAttributes (General)
• SecBuffer
• SecBufferDesc