InitializeSecurityContext (Negotiate) 函数
InitializeSecurityContext (Negotiate) 函数从凭据句柄启动客户端出站安全上下文。 函数用于在客户端应用程序和远程对等方之间生成 安全上下文 。 InitializeSecurityContext (Negotiate) 返回一个令牌，客户端必须传递给远程对等方，后者又通过 AcceptSecurityContext (协商) 调用提交到本地安全实现。 所有调用方都应将生成的令牌视为不透明。
通常，在建立足够的安全上下文之前，在循环中调用 InitializeSecurityContext (Negotiate) 函数。
语法
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 返回的凭据的句柄 (协商) 。 此句柄用于生成 安全上下文。 InitializeSecurityContext (Negotiate) 函数至少需要 OUTBOUND 凭据。
phContext[in, optional]
指向 CtxtHandle 结构的指针。 在首次调用 InitializeSecurityContext (Negotiate) 时，此指针为 NULL。 在第二次调用中，此参数是指向第一次调用在 phNewContext 参数中返回的部分格式上下文的句柄的指针。
警告
不要在 对 InitializeSecurityContext 的 并发调用中使用相同的上下文句柄， (协商) 。 安全服务提供程序中的 API 实现不是线程安全的。
pszTargetName[in, optional]
指向以 null 结尾的字符串的指针，该字符串指示服务主体名称 (SPN) 或目标服务器 的安全上下文 。
应用程序必须提供有效的 SPN 来帮助缓解重播攻击。
fContextReq[in]
指示上下文请求的位标志。 并非所有包都可以支持所有要求。 用于此参数的标志以 ISC_REQ_ 为前缀，例如，ISC_REQ_DELEGATE。 此参数可以是以下一个或多个属性标志。
| 值 | 含义 |
|---|---|
| ISC_REQ_ALLOCATE_MEMORY | 安全包会为你分配输出缓冲区。 使用完输出缓冲区后，通过调用 FreeContextBuffer 函数释放它们。 |
| ISC_REQ_CONFIDENTIALITY | 使用 EncryptMessage 函数加密 消息。 |
| ISC_REQ_CONNECTION | 安全上下文不会处理格式化消息。 此值为默认值。 |
| ISC_REQ_DELEGATE | 服务器可以使用上下文作为客户端向其他服务器进行身份验证。 必须设置 ISC_REQ_MUTUAL_AUTH 标志，此标志才能正常工作。 对 Kerberos 有效。 对于 受约束委派，请忽略此标志。 |
| ISC_REQ_EXTENDED_ERROR | 发生错误时，远程方将收到通知。 |
| ISC_REQ_INTEGRITY | 使用 EncryptMessage 和 MakeSignature 函数对消息进行签名和验证签名。 |
| ISC_REQ_MUTUAL_AUTH | 将满足服务的相互身份验证策略。 谨慎： 这并不一定意味着要执行相互身份验证，只意味着满足服务的身份验证策略。 若要确保执行相互身份验证，请调用 QueryContextAttributes (Negotiate) 函数。 |
| ISC_REQ_NO_INTEGRITY | 如果设置了此标志，则忽略 ISC_REQ_INTEGRITY 标志。 |
| ISC_REQ_REPLAY_DETECT | 检测已使用 EncryptMessage 或 MakeSignature 函数编码的重播消息。 |
| ISC_REQ_SEQUENCE_DETECT | 检测不按顺序接收的消息。 |
| ISC_REQ_STREAM | 支持面向流的连接。 |
客户端可能不支持请求的属性。 有关详细信息，请参阅 pfContextAttr 参数。
有关各种属性的进一步说明，请参阅 上下文要求。
Reserved1[in]
此参数是保留的，必须设置为零。
TargetDataRep[in]
目标上的数据表示形式，例如字节排序。 此参数可以是SECURITY_NATIVE_DREP或SECURITY_NETWORK_DREP。
pInput[in, optional]
指向 SecBufferDesc 结构的指针，该结构包含指向作为输入提供给包的缓冲区的指针。 除非客户端上下文由服务器启动，否则此参数的值必须在 NULL 首次调用函数时。 在对函数的后续调用或服务器启动客户端上下文时，此参数的值是指向分配的缓冲区的指针，该缓冲区具有足够的内存来保存远程计算机返回的令牌。
Reserved2[in]
此参数是保留的，必须设置为零。
phNewContext[in, out, optional]
指向 CtxtHandle 结构的指针。 在首次调用 InitializeSecurityContext (Negotiate) 时，此指针接收新的上下文句柄。 第二次调用 时，phNewContext 可以与 phContext 参数中指定的句柄相同。
phNewContext 不应为 NULL。
pOutput[in, out, optional]
指向 SecBufferDesc 结构的指针，该结构包含指向接收输出数据的 SecBuffer 结构的指针。 如果在输入中将缓冲区键入为SEC_READWRITE，则输出中将存在缓冲区。 如果通过ISC_REQ_ALLOCATE_MEMORY) 请求 (安全令牌，系统会为安全令牌分配缓冲区，并在安全令牌的缓冲区描述符中填写地址。
pfContextAttr[out]
指向变量的指针，用于接收一组指示已建立上下文 的属性 的位标志。 有关各种属性的说明，请参阅 上下文要求。
用于此参数的标志以 ISC_RET 为前缀，例如 ISC_RET_DELEGATE。 有关有效值的列表，请参阅 fContextReq 参数。
在最终函数调用成功返回之前，不要检查与安全相关的属性。 与安全性无关的属性标志（如ASC_RET_ALLOCATED_MEMORY标志）可以在最终返回之前进行检查。
注意
在与远程对等方协商期间，特定上下文属性可能会更改。
ptsExpiry[out, optional]
指向接收上下文过期时间的 TimeStamp 结构的指针。 建议 安全包 始终在本地时间返回此值。 此参数是可选的， NULL 应为生存期较短的客户端传递。
返回值
如果函数成功，该函数将返回以下成功代码之一。
| 返回代码 | 说明 |
|---|---|
| SEC_E_OK | 已成功初始化安全上下文。 无需另一个 InitializeSecurityContext (Negotiate) 调用。 如果函数返回输出令牌，即 pOutput 中的SECBUFFER_TOKEN长度为非零，则必须将令牌发送到服务器。 |
| SEC_I_COMPLETE_AND_CONTINUE | 客户端必须调用 CompleteAuthToken ，然后将输出传递给服务器。 然后，客户端等待返回的令牌，并在另一次调用中将其传递给 InitializeSecurityContext (Negotiate) 。 |
| SEC_I_COMPLETE_NEEDED | 客户端必须完成生成消息，然后调用 CompleteAuthToken 函数。 |
| SEC_I_CONTINUE_NEEDED | 客户端必须将输出令牌发送到服务器并等待返回令牌。 然后，在对 InitializeSecurityContext (Negotiate) 的另一次调用中传递返回的令牌。 输出令牌可以为空。 |
如果函数失败，该函数将返回以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
| 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 参数的主体不同。 这表示相互身份验证失败。 |
备注
调用方负责确定最终上下文属性是否足够。 例如，如果请求了机密性，但无法建立，则某些应用程序可能会选择立即关闭连接。
如果 安全上下文 的属性不足，客户端必须通过调用 DeleteSecurityContext 函数释放部分创建的上下文。
客户端使用 InitializeSecurityContext (Negotiate) 函数初始化出站上下文。
对于双腿 安全上下文，调用顺序如下：
- 客户端调用 将 phContext 设置为
NULL的 函数，并使用输入消息填充缓冲区描述符。 - 安全包检查参数并构造不透明令牌，并将其放置在缓冲区数组的 TOKEN 元素中。 如果 fContextReq 参数包含 ISC_REQ_ALLOCATE_MEMORY 标志， 则安全包 将分配内存并返回 TOKEN 元素中的指针。
- 客户端将 pOutput 缓冲区中返回的令牌发送到目标服务器。 然后，服务器在调用 AcceptSecurityContext (Negotiate) 函数时将令牌作为输入参数传递。
- AcceptSecurityContext (协商) 可能会返回一个令牌，如果第一个调用SEC_I_CONTINUE_NEEDED返回，服务器会将其发送给客户端，以便第二次调用 InitializeSecurityContext (Negotiate) 。
对于多段 安全上下文（例如相互身份验证），调用顺序如下：
- 客户端如前所述调用 函数，但包返回SEC_I_CONTINUE_NEEDED成功代码。
- 客户端将输出令牌发送到服务器，并等待服务器的回复。
- 收到服务器的响应后，客户端再次调用 InitializeSecurityContext (Negotiate) ，并将 phContext 设置为上次调用返回的句柄。 从服务器接收的令牌在 pInput 参数中提供。
- 不要在对 InitializeSecurityContext 的并发调用中使用 phContext 值 ， (协商) 。 安全提供程序中的实现不是线程安全的。
如果服务器已成功响应， 则安全包 将返回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 (Negotiate) 调用，并且服务器不会收到任何响应。 如果返回代码SEC_I_CONTINUE_NEEDED，则客户端需要来自服务器的响应令牌，并在第二次调用 InitializeSecurityContext (Negotiate) 传递它。 SEC_I_COMPLETE_NEEDED返回代码指示客户端必须完成消息生成并调用 CompleteAuthToken 函数。 SEC_I_COMPLETE_AND_CONTINUE代码合并了这两个操作。
如果 InitializeSecurityContext (Negotiate) 在第一个 (返回成功或仅) 调用，则调用方最终必须在返回的句柄上调用 DeleteSecurityContext 函数，即使调用在身份验证交换的后期失败也是如此。
客户端可以在成功完成后再次调用 InitializeSecurityContext (Negotiate) 。 这向 安全包 指示需要重新身份验证。
内核模式调用方具有以下差异：目标名称是必须使用 VirtualAlloc 在虚拟内存中分配的 Unicode 字符串;不得从池中分配它。 在 pInput 和 pOutput 中传递和提供的缓冲区必须位于虚拟内存中，而不是在池中。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2003 [仅限桌面应用] |
| 标头 | Sspi.h (包括 Security.h) |
| 库 | Secur32.lib |
| DLL | Secur32.dll |
另请参阅
AcceptSecurityContext (Negotiate)