Поделиться через

Функция EncryptMessage (Schannel)

  • Статья

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

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

Примечание

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

Синтаксис

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

Параметры

phContext [in]

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

fQOP [in]

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

Этот параметр может иметь следующий флаг.

Значение Значение
SECQOP_WRAP_OOB_DATA
 Отправка оповещения Schannel. В этом случае параметр pMessage должен содержать стандартный двухбайтовой код события SSL/TLS. Это значение поддерживается только поставщиком Schannel SSP.
Например, начиная с Windows Vista сообщение "server hello", отправленное сервером во время протокола повторной проверки подлинности, должно быть зашифровано как оповещение TLS.

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

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

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

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

MessageSeqNo [in]

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

При использовании 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 (Schannel) шифрует сообщение на основе сообщения и ключа сеанса из контекста безопасности.

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

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

Примечание

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

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

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

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

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

Требования

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

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