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 参数中返回的部分形式的上下文的句柄的指针。

psz目标名称[in, optional]

指向唯一标识目标服务器的以 null 结尾的字符串的指针。 Schannel 使用此值验证服务器证书。 Schannel 还使用此值在重新建立连接时在会话缓存中查找会话。 仅当满足以下所有条件时，才使用缓存会话：

• 目标名称相同。
• 缓存项尚未过期。
• 调用函数的应用程序进程相同。
• 登录会话相同。
• 凭据句柄相同。

fContextReq （f上下文请求）[in]

指示上下文请求的位标志。 并非所有包都支持所有要求。 用于此参数的标志以ISC_REQ_为前缀，例如ISC_REQ_DELEGATE。 此参数可以是以下一个或多个属性标志。

客户端可能不支持请求的属性。 有关详细信息，请参阅 pfContextAttr 参数。

有关各种属性的进一步说明，请参阅 上下文要求。

保留1[in]

此参数是保留的，必须设置为零。

TargetDataRep[in]

此参数不与 Schannel 一起使用。 将其设置为零。

pInput[in, optional]

指向 SecBufferDesc 结构的指针，该结构包含指向作为包输入提供的缓冲区的指针。 除非客户端上下文由服务器启动，否则此参数的值必须在 NULL 对函数的第一次调用中。 在对函数的后续调用或服务器启动客户端上下文时，此参数的值是指向分配有足够内存的缓冲区的指针，用于保存远程计算机返回的令牌。

在初始调用后调用此函数时，必须有两个缓冲区。 第一个类型 SECBUFFER_TOKEN 包含从服务器收到的令牌。 第二个缓冲区具有 类型SECBUFFER_EMPTY;将 pvBuffer 和 cbBuffer 成员都设置为零。

保留2[in]

此参数是保留的，必须设置为零。

phNewContext[in, out, optional]

指向 CtxtHandle 结构的指针。 在第一次调用 InitializeSecurityContext （Schannel）时，此指针接收新的上下文句柄。 第二次调用时， phNewContext 可以与 phContext 参数中指定的句柄相同。 phNewContext 不应该是 NULL。

p输出[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 应为生存期较短的客户端传递。

返回值

如果函数成功，该函数将返回以下成功代码之一。

如果函数失败，该函数将返回以下错误代码之一。

注解

调用方负责确定最终上下文属性是否足够。 例如，如果请求了机密性，但无法建立，某些应用程序可能会选择立即关闭连接。

如果 安全上下文 的属性不够，客户端必须通过调用 DeleteSecurityContext 函数释放部分创建的上下文。

InitializeSecurityContext （Schannel） 函数由客户端用来初始化出站上下文。

对于双腿 安全上下文，调用序列如下所示：

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

对于多回合 安全上下文（例如相互身份验证），调用顺序如下所示：

1. 客户端如前所述调用函数，但包返回SEC_I_CONTINUE_NEEDED成功代码。
2. 客户端将输出令牌发送到服务器，并等待服务器的回复。
3. 收到服务器的响应后，客户端将再次调用 InitializeSecurityContext （Schannel），并将 phContext 设置为上次调用返回的句柄。 从服务器收到的令牌在 pInput 参数中提供。
4. 请勿在对 InitializeSecurityContext（Schannel）的并发调用中使用 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 （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 参数中指定新凭据。

要求

另请参阅

SSPI 函数

AcceptSecurityContext （Schannel）

AcquireCredentialsHandle （Schannel）

完成身份验证令牌

删除SecurityContext

自由上下文缓冲区

秒缓冲区

SecBufferDesc