InitializeSecurityContext （CredSSP） 函数

InitializeSecurityContext （CredSSP） 函数从凭据句柄启动客户端出站安全上下文。 该函数在客户端应用程序和远程对等方之间生成安全上下文。 InitializeSecurityContext （CredSSP） 返回客户端必须传递给远程对等方的令牌;对等方又通过 AcceptSecurityContext （CredSSP） 调用将该令牌提交到本地安全实现。 所有调用方都应将生成的令牌视为不透明。

通常， InitializeSecurityContext （CredSSP） 函数在循环中调用，直到建立足够的安全上下文。

语法

SECURITY_STATUS SEC_ENTRY InitializeSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    SEC_CHAR       *pszTargetName,
  _In_        unsigned long  fContextReq,
  _Reserved_  unsigned long  Reserved1,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PSecBufferDesc pInput,
  _In_        unsigned long  Reserved2,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Out_opt_   PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

参数

phCredential 认证[in, optional]

AcquireCredentialsHandle （CredSSP） 返回的凭据的句柄。 此句柄用于生成安全上下文。 InitializeSecurityContext （CredSSP） 函数至少需要出站凭据。

phContext[in, optional]

指向 CtxtHandle 结构的指针。 在第一次调用 InitializeSecurityContext （CredSSP）时，此指针为 NULL。 在第二次调用中，此参数是指向第一次调用 在 phNewContext 参数中返回的部分格式上下文的句柄的指针。

在第一次调用 InitializeSecurityContext （CredSSP）时，指定 NULL。 在将来的调用中，指定在第一次调用此函数后 phNewContext 参数中收到的令牌。

p目标名称[in, optional]

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

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

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

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

此参数可以是以下一个或多个属性标志。

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

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

保留1[in]

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

TargetDataRep[in]

目标上的数据表示形式，例如字节顺序。 此参数可为 SECURITY_NATIVE_DREP 或 SECURITY_NETWORK_DREP。

pInput[in, out, optional]

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

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

保留2[in]

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

phNewContext[in, out, optional]

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

p输出[out, optional]

指向 SecBufferDesc 结构的指针。 此结构又包含指向接收输出数据的 SecBuffer 结构的指针。 如果缓冲区在输入中被键入 为SEC_READWRITE ，则会在输出中显示该缓冲区。 如果请求（通过 ISC_REQ_ALLOCATE_MEMORY），系统将为安全令牌分配缓冲区，并在安全令牌的缓冲区描述符中填写地址。

如果指定 了ISC_REQ_ALLOCATE_MEMORY 标志，CredSSP 将为缓冲区分配内存，并将相应的信息放在 SecBufferDesc 中。

pfContextAttr 的[out]

指向一组位标志的指针，这些标志指示已建立上下文 的属性 。 有关各种属性的说明，请参阅上下文要求。

用于此参数的标志以ISC_RET为前缀，例如 ISC_RET_DELEGATE。 有关有效值的列表，请参阅 fContextReq 参数。

在最终函数调用成功返回之前，不要检查与安全性相关的属性。 与安全性无关的属性标志（如 ASC_RET_ALLOCATED_MEMORY 标志）可以在最终返回之前进行检查。

ptsExpiry[out, optional]

指向接收上下文到期时间的 TimeStamp 结构的指针。 建议安全包始终在本地时间返回此值。 此参数是可选的， NULL 应为生存期较短的客户端传递。

返回值

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

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

注解

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

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

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

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

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

如果服务器已成功响应，安全包将返回 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 （CredSSP） 调用，并且不会收到来自服务器的响应。 如果返回代码 SEC_I_CONTINUE_NEEDED，则客户端需要来自服务器的令牌，并在第二次对 InitializeSecurityContext （CredSSP） 的调用中传递令牌。 SEC_I_COMPLETE_NEEDED返回代码指示客户端必须完成消息生成并调用 CompleteAuthToken 函数。 SEC_I_COMPLETE_AND_CONTINUE代码包含这两个作。

如果 InitializeSecurityContext （CredSSP） 在第一次（或仅）调用中返回成功，则调用方最终必须在返回的句柄上调用 DeleteSecurityContext 函数，即使调用在身份验证交换的后续部分失败。

客户端在成功完成后可能会再次调用 InitializeSecurityContext （CredSSP ）。 这向安全包指示需要重新身份验证。

内核模式调用方具有以下差异：目标名称是必须使用 VirtualAlloc 在虚拟内存中分配的 Unicode 字符串;不能从池中分配它。 在 pInput 和 pOutput 中传递和提供的缓冲区必须位于虚拟内存中，而不是池中。

如果函数返回 SEC_I_INCOMPLETE_CREDENTIALS，请检查传递给 AcquireCredentialsHandle （CredSSP） 函数的 r 凭据是否指定了有效且受信任的证书。证书必须是由服务器信任的证书颁发机构颁发的客户端身份验证证书。 若要获取服务器信任的 CA 列表，请使用 SECPKG_ATTR_ISSUER_LIST_EX 属性调用 QueryContextAttributes （CredSSP） 函数。

从服务器信任的证书颁发机构接收身份验证证书后，客户端应用程序会创建新的凭据。 它通过调用 AcquireCredentialsHandle （CredSSP） 函数，然后再次调用 InitializeSecurityContext （CredSSP）， 并在 phCredential 参数中指定新凭据来执行此作。

要求

另请参阅

SSPI 函数

AcceptSecurityContext （CredSSP）

AcquireCredentialsHandle （CredSSP）

完成身份验证令牌

删除SecurityContext

自由上下文缓冲区

秒缓冲区

SecBufferDesc