通过

EncryptMessage (Schannel) 函数

  • 项目

EncryptMessage (Schannel) 函数加密消息以提供隐私。 EncryptMessage (Schannel) 允许应用程序在所选机制支持的 加密算法 中进行选择。 EncryptMessage (Schannel) 函数使用上下文句柄引用的安全上下文。 某些包没有要加密或解密的消息，而是提供可检查的完整性 哈希 。

使用 Schannel SSP 时，此函数使用与将接收消息的远程方协商的 会话密钥 来加密消息。 加密算法由正在使用的 [密码 套件] (密码 suites-in-schannel.md) 确定。

注意

如果一个线程正在加密，另一个线程正在解密，则可以同时从单个安全支持提供程序接口中的两个不同线程调用 EncryptMessage ( (Schannel) 和 DecryptMessage) (Schannel ) 。 如果多个线程正在加密，或者多个线程正在解密，则每个线程应获取唯一的上下文。

语法

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

parameters

phContext [in]

用于加密消息 的安全上下文 的句柄。

fQOP [in]

指示保护质量的包特定标志。 安全包可以使用此参数来启用加密算法的选择。

此参数可以是以下标志。

值 含义
SECQOP_WRAP_OOB_DATA
 发送 Schannel 警报消息。 在这种情况下， pMessage 参数必须包含标准的双字节 SSL/TLS 事件代码。 只有 Schannel SSP 支持此值。
例如，从 Windows Vista 开始，服务器在重新身份验证协议期间发送的“服务器 hello”消息必须加密为 TLS 警报。

pMessage [in， out]

指向 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

另请参阅