EncryptMessage 函数 (sspi.h)

项目
08/26/2023

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

此函数仅可用作 SASL 机制。

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

语法

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

参数

[in] phContext

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

[in] fQOP

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

使用摘要 SSP 时，此参数必须设置为零。

[in, out] pMessage

指向 SecBufferDesc 结构的指针。在输入时，结构引用一个或多个可SECBUFFER_DATA类型的 SecBuffer 结构。该缓冲区包含要加密的消息。消息已就地加密，覆盖结构的原始内容。

函数不处理具有 SECBUFFER_READONLY 属性的缓冲区。

包含消息的 SecBuffer 结构的长度不能大于 cbMaximumMessage，该长度是从 QueryContextAttributes (Digest) (SECPKG_ATTR_STREAM_SIZES) 函数获取的。

使用摘要 SSP 时，必须有第二个类型为 SECBUFFER_PADDING 或 SEC_BUFFER_DATA 的缓冲区来保存签名信息。若要获取输出缓冲区的大小，请调用 QueryContextAttributes (Digest) 函数并指定SECPKG_ATTR_SIZES。函数将返回 SecPkgContext_Sizes 结构。输出缓冲区的大小是 cbMaxSignature 和 cbBlockSize 成员中的值之和。

不使用 SSL 的应用程序必须提供 SECBUFFER_PADDING 类型的 SecBuffer 。

[in] MessageSeqNo

传输应用程序分配给消息的序列号。如果传输应用程序不保留序列号，则此参数必须为零。

使用摘要 SSP 时，此参数必须设置为零。摘要 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 (摘要) 函数基于消息和来自安全上下文的会话密钥加密消息。

如果传输应用程序创建了支持序列检测的安全上下文，并且调用方提供了序列号，则函数会将此信息与加密消息一起包含在内。包含此信息可防止重播、插入和抑制消息。安全包包含从传输应用程序向下传递的序列号。

使用摘要 SSP 时，通过调用 QueryContextAttributes (Digest) 函数并指定SECPKG_ATTR_SIZES来获取输出缓冲区的大小。函数将返回 SecPkgContext_Sizes 结构。输出缓冲区的大小是 cbMaxSignature 和 cbBlockSize 成员中的值之和。

注意必须按显示的顺序提供这些缓冲区。

缓冲区类型	说明
SECBUFFER_STREAM_HEADER	内部使用。无需初始化。
SECBUFFER_DATA	包含要加密的纯文本消息。
SECBUFFER_STREAM_TRAILER	内部使用。无需初始化。
SECBUFFER_EMPTY	内部使用。无需初始化。大小可以为零。

为了获得最佳性能，应从连续内存中分配 pMessage 结构。

Windowsxp： 此函数也称为 SealMessage。应用程序现在应仅使用 EncryptMessage (Digest) 。

要求


最低受支持的客户端	Windows XP [仅限桌面应用]
最低受支持的服务器	Windows Server 2003 [仅限桌面应用]
目标平台	Windows
标头	sspi.h (包括 Security.h)
Library	Secur32.lib
DLL	Secur32.dll