InitializeSecurityContext (Schannel) 函数
InitializeSecurityContext (Schannel) 函数从凭据句柄启动客户端出站安全上下文。 函数用于在客户端应用程序和远程对等方之间生成 安全上下文 。 InitializeSecurityContext (Schannel) 返回客户端必须传递给远程对等方的令牌，而对等方又通过 AcceptSecurityContext (Schannel) 调用提交到本地安全实现。 所有调用方都应将生成的令牌视为不透明。
通常，在建立足够的安全上下文之前，在循环中调用 InitializeSecurityContext (Schannel) 函数。
语法
SECURITY_STATUS SEC_Entry InitializeSecurityContext(
_In_opt_ PCredHandle phCredential,
_In_opt_ PCtxtHandle phContext,
_In_opt_ SEC_CHAR *pszTargetName,
_In_ ULONG fContextReq,
_In_ ULONG Reserved1,
_In_ ULONG TargetDataRep,
_In_opt_ PSecBufferDesc pInput,
_In_ ULONG Reserved2,
_Inout_opt_ PCtxtHandle phNewContext,
_Inout_opt_ PSecBufferDesc pOutput,
_Out_ PULONG pfContextAttr,
_Out_opt_ PTimeStamp ptsExpiry
);
参数
phCredential[in, optional]
AcquireCredentialsHandle (Schannel 返回的凭据的句柄) 。 此句柄用于生成 安全上下文。 InitializeSecurityContext (Schannel) 函数在第一次调用时至少需要出站凭据。 在后续调用中，这可以是 NULL。
phContext[in, optional]
指向 CtxtHandle 结构的指针。 在首次调用 InitializeSecurityContext (Schannel) 时，此指针为 NULL。 在将来的调用中，此参数是指向第一次调用此函数时在 phNewContext 参数中返回的部分格式上下文的句柄的指针。
警告
不要在对 InitializeSecurityContext (Schannel) 的并发调用中使用相同的上下文句柄。 安全服务提供程序中的 API 实现不是线程安全的。
pszTargetName[in, optional]
指向以 null 结尾的字符串的指针，该字符串唯一标识目标服务器。 Schannel 使用此值来验证服务器证书。 重新建立连接时，Schannel 还使用此值在会话缓存中查找会话。 仅当满足以下所有条件时，才使用缓存的会话：
- 目标名称相同。
- 缓存项未过期。
- 调用函数的应用程序进程是相同的。
- 登录会话是相同的。
- 凭据句柄是相同的。
fContextReq[in]
指示上下文请求的位标志。 并非所有包都可以支持所有要求。 用于此参数的标志带有ISC_REQ_前缀，例如，ISC_REQ_DELEGATE。 此参数可以是以下一个或多个属性标志。
| 值 | 含义 |
|---|---|
| ISC_REQ_ALLOCATE_MEMORY | 安全包会为你分配输出缓冲区。 使用完输出缓冲区后，通过调用 FreeContextBuffer 函数释放它们。 |
| ISC_REQ_CONFIDENTIALITY | 使用 EncryptMessage 函数加密消息。 |
| ISC_REQ_CONNECTION | 安全上下文不会处理格式设置消息。 |
| ISC_REQ_EXTENDED_ERROR | 发生错误时，远程方将收到通知。 |
| ISC_REQ_INTEGRITY | 使用 EncryptMessage 和 MakeSignature 函数对消息进行签名和验证签名。 |
| ISC_REQ_MANUAL_CRED_VALIDATION | Schannel 不得自动对服务器进行身份验证。 |
| ISC_REQ_MUTUAL_AUTH | 将满足服务的相互身份验证策略。 谨慎： 这并不一定意味着执行相互身份验证，只意味着满足服务的身份验证策略。 若要确保执行相互身份验证，请调用 QueryContextAttributes (Schannel) 函数。 |
| ISC_REQ_REPLAY_DETECT | 检测已使用 EncryptMessage 或 MakeSignature 函数编码的重播消息。 |
| ISC_REQ_SEQUENCE_DETECT | 检测按顺序接收的消息。 |
| ISC_REQ_STREAM | 支持面向流的连接。 |
| ISC_REQ_USE_SUPPLIED_CREDS | Schannel 不得尝试自动为客户端提供凭据。 |
客户端可能不支持请求的属性。 有关详细信息，请参阅 pfContextAttr 参数。
有关各种属性的进一步说明，请参阅 上下文要求。
Reserved1[in]
此参数是保留的，必须设置为零。
TargetDataRep[in]
此参数不与 Schannel 一起使用。 将其设置为零。
pInput[in, optional]
指向 SecBufferDesc 结构的指针，该结构包含指向作为包输入提供的缓冲区的指针。 除非客户端上下文由服务器启动，否则此参数的值必须在 NULL 首次调用函数时使用。 在后续调用函数或服务器启动客户端上下文时，此参数的值是指向分配的缓冲区的指针，该缓冲区分配了足够的内存来保存远程计算机返回的令牌。
在初始调用后调用此函数时，必须有两个缓冲区。 第一个 类型 为 SECBUFFER_TOKEN ，并且包含从服务器收到的令牌。 第二个缓冲区的类型 为 SECBUFFER_EMPTY;将 pvBuffer 和 cbBuffer 成员都设置为零。
Reserved2[in]
此参数是保留的，必须设置为零。
phNewContext[in, out, optional]
指向 CtxtHandle 结构的指针。 在第一次调用 InitializeSecurityContext (Schannel) 时，此指针接收新的上下文句柄。 第二次调用时， phNewContext 可以与 phContext 参数中指定的句柄相同。 phNewContext 绝不应为 NULL。
pOutput[in, out, optional]
指向 SecBufferDesc 结构的指针，该结构包含指向接收输出数据的 SecBuffer 结构的指针。 如果在输入中将缓冲区键入为SEC_READWRITE，则输出中会存在缓冲区。 如果通过ISC_REQ_ALLOCATE_MEMORY) 请求 (安全令牌，系统将为安全令牌分配缓冲区，并在安全令牌的缓冲区描述符中填写地址。
如果指定ISC_REQ_ALLOCATE_MEMORY标志，Schannel SSP 将为缓冲区分配内存，并将相应信息放入 SecBufferDesc 中。 此外，调用方必须传入 SECBUFFER_ALERT 类型的缓冲区。 在输出中，如果生成警报，则此缓冲区包含有关该警报的信息，并且函数会失败。
pfContextAttr[out]
指向变量的指针，用于接收一组指示已建立上下文 的属性 的位标志。 有关各种属性的说明，请参阅 上下文要求。
用于此参数的标志以ISC_RET为前缀，例如ISC_RET_DELEGATE。 有关有效值的列表，请参阅 fContextReq 参数。
在最终函数调用成功返回之前，不要检查与安全相关的属性。 可以在最终返回之前检查与安全性无关的属性标志，例如ASC_RET_ALLOCATED_MEMORY标志。
注意
在与远程对等方协商期间，特定上下文属性可能会更改。
ptsExpiry[out, optional]
指向接收上下文过期时间的 TimeStamp 结构的指针。 建议 安全包 始终在本地时间返回此值。 此参数是可选的， NULL 应为生存期较短的客户端传递。
返回值
如果函数成功，该函数将返回以下成功代码之一。
| 返回代码 | 说明 |
|---|---|
| SEC_I_COMPLETE_AND_CONTINUE | 客户端必须调用 CompleteAuthToken ，然后将输出传递给服务器。 然后，客户端等待返回的令牌，并在另一次调用中将其传递到 InitializeSecurityContext (Schannel) 。 |
| SEC_I_COMPLETE_NEEDED | 客户端必须完成消息的生成，然后调用 CompleteAuthToken 函数。 |
| SEC_I_CONTINUE_NEEDED | 客户端必须将输出令牌发送到服务器并等待返回令牌。 然后，返回的令牌在对 InitializeSecurityContext (Schannel) 调用中传递。 输出令牌可以为空。 |
| SEC_I_INCOMPLETE_CREDENTIALS | 服务器已请求客户端身份验证，并且提供的凭据不包括证书，或者证书不是由证书颁发机构颁发的， (CA) 服务器信任。 有关详细信息，请参阅“备注”。 |
| SEC_E_INCOMPLETE_MESSAGE | 未从线路中读取整个消息的数据。 返回此值时， pInput 缓冲区包含一个 SecBuffer 结构， 其 BufferType 成员 为 SECBUFFER_MISSING。 SecBuffer 的 cbBuffer 成员包含一个值，该值指示函数在此函数成功之前必须从客户端读取的其他字节数。 虽然此数字并非始终准确，但使用它可避免多次调用此函数，从而帮助提高性能。 |
| SEC_E_OK | 已成功初始化安全上下文。 无需另一个 InitializeSecurityContext (Schannel) 调用。 如果函数返回输出标记，即 pOutput 中的SECBUFFER_TOKEN长度为非零，则必须将该令牌发送到服务器。 |
如果函数失败，该函数将返回以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
| SEC_E_INSUFFICIENT_MEMORY | 没有足够的内存可用于完成请求的操作。 |
| SEC_E_INTERNAL_ERROR | 发生了未映射到 SSPI 错误代码的错误。 |
| SEC_E_INVALID_HANDLE | 传递给函数的句柄无效。 |
| SEC_E_INVALID_TOKEN | 此错误是由于输入令牌格式不正确，例如令牌在传输中损坏、令牌大小不正确或令牌传递到错误的 受约束委派中。 如果客户端和服务器未协商适当的 约束委派，则可能会将令牌传递到错误的包。 |
| SEC_E_LOGON_DENIED | 登录失败。 |
| SEC_E_NO_AUTHENTICATING_AUTHORITY | 无法联系任何机构进行身份验证。 身份验证方的域名可能不正确，域可能无法访问，或者可能存在信任关系失败。 |
| SEC_E_NO_CREDENTIALS | 约束委派中没有可用的凭据。 |
| SEC_E_TARGET_UNKNOWN | 无法识别目标。 |
| SEC_E_UNSUPPORTED_FUNCTION | 在 fContextReq 参数中指定了无效 (ISC_REQ_DELEGATE或ISC_REQ_PROMPT_FOR_CREDS) 的上下文属性标志。 |
| SEC_E_WRONG_PRINCIPAL | 接收身份验证请求的主体与传递到 pszTargetName 参数的主体不同。 这表示相互身份验证失败。 |
| SEC_E_APPLICATION_PROTOCOL_MISMATCH | 客户端和服务器之间不存在常见的应用程序协议。 |
备注
调用方负责确定最终的上下文属性是否足够。 例如，如果请求了机密性，但无法建立，则某些应用程序可能会选择立即关闭连接。
如果 安全上下文 的属性不够，客户端必须通过调用 DeleteSecurityContext 函数释放部分创建的上下文。
客户端使用 InitializeSecurityContext (Schannel) 函数初始化出站上下文。
对于双腿 安全上下文，调用顺序如下：
- 客户端调用将 phContext 设置为
NULL的 函数，并使用输入消息填充缓冲区描述符。 - 安全包检查参数并构造一个不透明的令牌，并将其放置在缓冲区数组的 TOKEN 元素中。 如果 fContextReq 参数包含 ISC_REQ_ALLOCATE_MEMORY 标志， 则安全包 将分配内存并返回 TOKEN 元素中的指针。
- 客户端将 pOutput 缓冲区中返回的令牌发送到目标服务器。 然后，服务器在调用 AcceptSecurityContext (Schannel) 函数时将令牌作为输入参数传递。
- AcceptSecurityContext (Schannel) 可能会返回一个令牌，如果第一次调用SEC_I_CONTINUE_NEEDED返回，则服务器会向客户端发送令牌，以便第二次调用 InitializeSecurityContext (Schannel) 。
对于多段 安全上下文（例如相互身份验证），调用顺序如下所示：
- 客户端如前所述调用函数，但包返回SEC_I_CONTINUE_NEEDED成功代码。
- 客户端将输出令牌发送到服务器，并等待服务器的回复。
- 收到服务器的响应后，客户端再次调用 InitializeSecurityContext (Schannel) ， 并将 phContext 设置为从上次调用返回的句柄。 从服务器接收的令牌在 pInput 参数中提供。
- 请勿在对 InitializeSecurityContext 的并发调用中使用 phContext 值， (Schannel) 。 安全提供程序中的实现不是线程安全的。
如果服务器已成功响应， 则安全包 将返回SEC_E_OK并建立安全会话。
如果函数返回错误响应之一，则不接受服务器的响应，并且不会建立会话。
如果函数返回SEC_I_CONTINUE_NEEDED、SEC_I_COMPLETE_NEEDED或SEC_I_COMPLETE_AND_CONTINUE，则重复步骤 2 和 3。
若要初始化 安全上下文，可能需要多次调用此函数，具体取决于基础身份验证机制以及在 fContextReq 参数中指定的选项。
fContextReq 和 pfContextAttributes 参数是表示各种上下文属性的位掩码。 有关各种属性的说明，请参阅 上下文要求。 pfContextAttributes 参数对任何成功返回都有效，但只有在最终成功返回时，才应检查与上下文安全方面相关的标志。 例如，中间返回可以设置ISC_RET_ALLOCATED_MEMORY标志。
如果设置了ISC_REQ_USE_SUPPLIED_CREDS标志， 则安全包 必须在 pInput 输入缓冲区中查找SECBUFFER_PKG_PARAMS缓冲区类型。 这不是泛型解决方案，但它允许在适当的时候对 安全包 和应用程序进行强配对。
如果指定了ISC_REQ_ALLOCATE_MEMORY，则调用方必须通过调用 FreeContextBuffer 函数来释放内存。
例如，输入令牌可能是来自 LAN 管理器的质询。 在这种情况下，输出令牌将是对质询的 NTLM 加密响应。
客户端执行的操作取决于此函数的返回代码。 如果返回代码SEC_E_OK，则不会有第二个 InitializeSecurityContext (Schannel) 调用，并且服务器不会做出响应。 如果返回代码SEC_I_CONTINUE_NEEDED，则客户端需要一个令牌来响应服务器，并在第二次调用 InitializeSecurityContext (Schannel) 传递它。 SEC_I_COMPLETE_NEEDED返回代码指示客户端必须完成消息生成并调用 CompleteAuthToken 函数。 SEC_I_COMPLETE_AND_CONTINUE代码合并了这两个操作。
如果 InitializeSecurityContext (Schannel) 在第一个 (或仅) 调用返回成功，则调用方最终必须在返回的句柄上调用 DeleteSecurityContext 函数，即使调用在身份验证交换的后续部分失败也是如此。
客户端可以在成功完成后再次调用 InitializeSecurityContext (Schannel) 。 这向 安全包 指示需要重新身份验证。
内核模式调用方具有以下差异：目标名称是必须使用 VirtualAlloc 在虚拟内存中分配的 Unicode 字符串;不得从池中分配它。 在 pInput 和 pOutput 中传递和提供的缓冲区必须位于虚拟内存中，而不是在池中。
如果函数返回SEC_I_INCOMPLETE_CREDENTIALS，检查在凭据中指定了有效且受信任的证书。 证书是在调用 AcquireCredentialsHandle (Schannel) 函数时指定的。 证书必须是证书颁发机构颁发的客户端身份验证证书， (CA) 服务器信任。 若要获取服务器信任的 CA 的列表，请调用 QueryContextAttributes (Schannel) 函数并指定 SECPKG_ATTR_ISSUER_LIST_EX 属性。
客户端应用程序从服务器信任的 CA 收到身份验证证书后，该应用程序通过调用 AcquireCredentialsHandle (Schannel) 函数，然后再次调用 InitializeSecurityContext (Schannel) ，并在 phCredential 参数中指定新凭据，从而创建新的凭据。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows 8.1 [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2012 R2 [仅限桌面应用] |
| 标头 | Sspi.h (包括 Security.h) |
| 库 | Secur32.lib |
| DLL | Secur32.dll |
另请参阅
AcceptSecurityContext (Schannel)
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈