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 使用 EncryptMessageMakeSignature 函数对消息进行签名和验证签名。
ISC_REQ_MUTUAL_AUTH 将满足服务的相互身份验证策略。
谨慎: 这并不一定意味着要执行相互身份验证,只意味着满足服务的身份验证策略。 若要确保执行相互身份验证,请调用 QueryContextAttributes (Negotiate) 函数。
ISC_REQ_NO_INTEGRITY 如果设置了此标志,则忽略 ISC_REQ_INTEGRITY 标志。
ISC_REQ_REPLAY_DETECT 检测已使用 EncryptMessageMakeSignature 函数编码的重播消息。
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) 函数初始化出站上下文。

对于双腿 安全上下文,调用顺序如下:

  1. 客户端调用 将 phContext 设置为 NULL 的 函数,并使用输入消息填充缓冲区描述符。
  2. 安全包检查参数并构造不透明令牌,并将其放置在缓冲区数组的 TOKEN 元素中。 如果 fContextReq 参数包含 ISC_REQ_ALLOCATE_MEMORY 标志, 则安全包 将分配内存并返回 TOKEN 元素中的指针。
  3. 客户端将 pOutput 缓冲区中返回的令牌发送到目标服务器。 然后,服务器在调用 AcceptSecurityContext (Negotiate) 函数时将令牌作为输入参数传递。
  4. AcceptSecurityContext (协商) 可能会返回一个令牌,如果第一个调用SEC_I_CONTINUE_NEEDED返回,服务器会将其发送给客户端,以便第二次调用 InitializeSecurityContext (Negotiate)

对于多段 安全上下文(例如相互身份验证),调用顺序如下:

  1. 客户端如前所述调用 函数,但包返回SEC_I_CONTINUE_NEEDED成功代码。
  2. 客户端将输出令牌发送到服务器,并等待服务器的回复。
  3. 收到服务器的响应后,客户端再次调用 InitializeSecurityContext (Negotiate) ,并将 phContext 设置为上次调用返回的句柄。 从服务器接收的令牌在 pInput 参数中提供。
  4. 不要在对 InitializeSecurityContext 的并发调用中使用 phContext, (协商) 。 安全提供程序中的实现不是线程安全的。

如果服务器已成功响应, 则安全包 将返回SEC_E_OK并建立安全会话。

如果函数返回错误响应之一,则不接受服务器的响应,并且不会建立会话。

如果函数返回SEC_I_CONTINUE_NEEDED、SEC_I_COMPLETE_NEEDED或SEC_I_COMPLETE_AND_CONTINUE,则重复步骤 2 和 3。

若要初始化 安全上下文,可能需要多次调用此函数,具体取决于基础身份验证机制以及在 fContextReq 参数中指定的选项。

fContextReqpfContextAttributes 参数是表示各种上下文属性的位掩码。 有关各种属性的说明,请参阅 上下文要求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 字符串;不得从池中分配它。 在 pInputpOutput 中传递和提供的缓冲区必须位于虚拟内存中,而不是在池中。

要求

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

另请参阅

SSPI 函数

AcceptSecurityContext (Negotiate)

AcquireCredentialsHandle (Negotiate)

CompleteAuthToken

DeleteSecurityContext

FreeContextBuffer

SecBuffer

SecBufferDesc