AcceptSecurityContext (CredSSP) 函数

项目
07/23/2024

AcceptSecurityContext (CredSSP) 函数允许传输应用程序的服务器组件在服务器与远程客户端之间建立安全上下文。远程客户端会调用 InitializeSecurityContext (CredSSP) 函数来启动建立安全上下文的流程。服务器可能需要来自远程客户端的一个或多个回复令牌才能完成安全上下文的建立。

语法

SECURITY_STATUS SEC_ENTRY AcceptSecurityContext(
  _In_opt_    PCredHandle    phCredential,
  _In_opt_    PCtxtHandle    phContext,
  _In_opt_    PSecBufferDesc pInput,
  _In_        unsigned long  fContextReq,
  _In_        unsigned long  TargetDataRep,
  _Inout_opt_ PCtxtHandle    phNewContext,
  _Inout_opt_ PSecBufferDesc pOutput,
  _Out_       unsigned long  *pfContextAttr,
  _Out_opt_   PTimeStamp     ptsExpiry
);

参数

phCredential [in, optional]

服务器凭据的句柄。若要检索此句柄，服务器将使用 SECPKG_CRED_INBOUND 或 SECPKG_CRED_BOTH 标志集来调用 AcquireCredentialsHandle (CredSSP) 函数。

phContext [in, optional]

指向 CtxtHandle 结构的指针。第一次调用 AcceptSecurityContext (CredSSP)时，该指针为 NULL。在后续调用中，phContext 会指定首次调用在 phNewContext 参数中返回的已部分形成的上下文。

警告

请勿在对 AcceptSecurityContext (CredSSP) 的并发调用中使用同一上下文句柄。安全服务提供商中的 API 实现的线程不安全。

pInput [in, optional]

对 InitializeSecurityContext (CredSSP) 的客户端调用所生成 SecBufferDesc 结构的指针。此结构包含输入缓冲区描述符。

第一个缓冲区必须为 SECBUFFER_TOKEN 类型，且包含从客户端接收的安全令牌。第二个缓冲区应为 SECBUFFER_EMPTY 类型。

fContextReq [in]

-位标志，可用于指定服务器建立上下文所需的属性。可使用逐位 OR 运算来组合位标志。此参数可使用以下一个或多个值。

值	含义
ASC_REQ_ALLOCATE_MEMORY	凭据安全支持提供程序 (CredSSP) 会分配输出缓冲区。使用完输出缓冲区后，通过调用 FreeContextBuffer 函数释放它们。
ASC_REQ_CONNECTION	安全上下文不会处理格式化消息。
ASC_REQ_DELEGATE	允许服务器模拟客户端。为约束委派忽略此标志。
ASC_REQ_EXTENDED_ERROR	发生错误时，将通知远程方。
ASC_REQ_REPLAY_DETECT	检测重播的数据包。
ASC_REQ_SEQUENCE_DETECT	检测按顺序接收的消息。
ASC_REQ_STREAM	支持面向流的连接。

有关可能的属性标志及其含义，请参阅上下文要求。用于此参数的标志会以 ASC_REQ 作为前缀，例如 ASC_REQ_DELEGATE。

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

TargetDataRep [in]

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

phNewContext [in, out, optional]

指向 CtxtHandle 结构的指针。首次调用 AcceptSecurityContext (CredSSP)时，该指针会接收新的上下文句柄。在后续调用中，phNewContext 可与 phContext 参数中指定的句柄相同。

pOutput [in, out, optional]

包含输出缓冲区描述符的 SecBufferDesc 结构的指针。此缓冲区会发送到客户端，以便输入到对 InitializeSecurityContext (CredSSP) 的其他调用中。即使此函数返回 SEC_E_OK，也可能会生成输出缓冲区。生成的所有缓冲区均须发送回客户端应用程序。

在输出中，此缓冲区会接收安全上下文的令牌。必须将此令牌发送到客户端。该函数还可返回 SECBUFFER_EXTRA 类型的缓冲区。

pfContextAttr [out]

一组位标志的指针，而这些标志表示已建立上下文的属性。有关各种属性的说明，请参阅上下文要求。用于此参数的标志会以 ASC_RET 作为前缀，例如 ASC_RET_DELEGATE。

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

ptsExpiry [out, optional]

指向接收上下文到期时间的 TimeStamp 结构的指针。我们建议安全包始终以本地时间返回此值。

注意

在上次调用身份验证流程结束之前，上下文的过期时间可能不正确，因为在协商的后续阶段会提供更多信息。因此，ptsTimeStamp 必须一直为 NULL，直到对此函数的最后一次调用结束。

返回值

此函数将返回下列值之一。

返回代码/值	说明
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	函数成功。输入缓冲区中的数据不完整。应用程序必须从客户端读取其他数据，并再次调用 AcceptSecurityContext (CredSSP)。
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	此函数失败。没有足够的内存可用于完成请求的操作。
SEC_E_INTERNAL_ERROR 0x80090304L	此函数失败。出现未映射到 SSPI 错误代码的错误。
SEC_E_INVALID_HANDLE 0x80100003L	此函数失败。传递到函数的句柄无效。
SEC_E_INVALID_TOKEN 0x80090308L	此函数失败。传递给函数的令牌无效。
SEC_E_LOGON_DENIED 0x8009030CL	登录失败。
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	此函数失败。无法联系任何机构进行身份验证。这可能是由以下情况造成的：身份验证方的域名不正确。域不可用。信任关系已失败。
SEC_E_NO_CREDENTIALS 0x8009030EL	此函数失败。 phCredential 参数中指定的凭据句柄无效。
SEC_E_OK 0x00000000L	函数成功。已接受从客户端接收的安全上下文。如果此函数生成了输出令牌，则须将此令牌发送到客户端进程。
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	此函数失败。 fContextReq 参数指定了无效上下文属性标志（ASC_REQ_DELEGATE 或 ASC_REQ_PROMPT_FOR_CREDS）。
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	函数成功。服务器必须调用 CompleteAuthToken 并将输出令牌传递给客户端。然后，服务器必须等待来自客户端的返回令牌，然后再调用 AcceptSecurityContext (CredSSP)。
SEC_I_COMPLETE_NEEDED 0x00090313L	函数成功。在调用 CompleteAuthToken 之前，服务器必须完成从客户端生成消息
SEC_I_CONTINUE_NEEDED 0x00090312L	函数成功。服务器必须将输出令牌发送到客户端，并等待返回的令牌。返回的令牌应在 pInput 中传递，以便再次调用 AcceptSecurityContext (CredSSP)。

注解

AcceptSecurityContext (CredSSP) 函数是与 InitializeSecurityContext (CredSSP) 函数对应的服务器。

当服务器从客户端接收请求时，它会使用 fContextReq 参数来指定对会话的要求。如此一来，服务器便可要求客户端能使用机密或已完成完整性检查的会话；它可拒绝无法满足该要求的客户端。或者，服务器也可不做任何要求；无论客户端需要或可提供什么，均会在 pfContextAttr 参数中返回。

fContextReq 和 pfContextAttr 参数是用于表示各种上下文属性的位掩码。有关各种属性的说明，请参阅上下文要求。

注意

虽然 pfContextAttr 参数在任意成功的返回时均有效，但应仅在最后成功返回时检查与上下文的安全方面相关的标志。中间返回可以设置 ISC_RET_ALLOCATED_MEMORY 标志。

调用方负责确定最终上下文属性是否足够。例如，如果要求建立机密性（加密）但无法成功完成，某些应用程序则可能会选择立即关闭此连接。如果无法建立安全上下文，服务器则须通过调用 DeleteSecurityContext 函数来释放已部分创建的上下文。有关何时调用 DeleteSecurityContext 函数的信息，请参阅 DeleteSecurityContext。

建立安全上下文后，服务器应用程序可使用 QuerySecurityContextToken 函数来检索客户端证书所映射到的用户帐户的句柄。此外，服务器还可使用 ImpersonateSecurityContext 函数来模拟用户。

要求

要求	值
最低受支持的客户端	Windows�Vista [仅限桌面应用]
支持的最低服务器版本	Windows Server�2008 [仅限桌面应用]
头文件	Sspi.h（包括 Security.h）
库	Secur32.lib
DLL	Secur32.dll

通过

AcceptSecurityContext (CredSSP) 函数

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源