SspiAcquireCredentialsHandleAsyncW 函数 (sspi.h)
SspiAcquireCredentialsHandleAsyncW 函数异步获取安全主体的预先存在的凭据的句柄。
SspiInitializeSecurityContextAsync 和 SspiAcceptSecurityContextAsync 函数需要此句柄。 这些凭据可以是预先存在的凭据，这些 凭据是通过此处未介绍的系统登录建立的，也可以是调用方可以提供替代凭据。
注意
此函数充当 AcquireCredentialsHandle 的异步对应函数。
语法
SECURITY_STATUS SspiAcquireCredentialsHandleAsyncW(
SspiAsyncContext *AsyncContext,
PSECURITY_STRING pszPrincipal,
PSECURITY_STRING pszPackage,
unsigned long fCredentialUse,
void *pvLogonId,
void *pAuthData,
SEC_GET_KEY_FN pGetKeyFn,
void *pvGetKeyArgument,
PCredHandle phCredential,
PTimeStamp ptsExpiry
);
参数
AsyncContext
异步调用上下文。
pszPrincipal
指向以 null 结尾的字符串的指针，该字符串指定句柄将以异步方式引用其凭据的主体的名称。
注意
如果请求句柄的进程无权访问凭据，则函数将返回错误。 null 字符串指示进程需要对其 执行其安全上下文 的用户凭据的句柄。
pszPackage
指向以 null 结尾的字符串的指针，该字符串指定要使用这些凭据 的安全包 的名称。 这是在 EnumerateSecurityPackages 函数返回的 SecPkgInfo 结构的 Name 成员中返回的安全包名称。 建立上下文后，可以使用 ulAttribute 设置为 SECPKG_ATTR_PACKAGE_INFO 调用 QueryContextAttributes (CredSSP ) ，以返回有关正在使用的安全包的信息。
fCredentialUse
指示如何使用这些凭据的标志。 此参数可能是以下值之一：
值 |
含义 |
|---|---|
| SECPKG_CRED_INBOUND | 验证传入服务器凭据。 调用 SspiInitializeSecurityContextAsync 或 SspiAcceptSecurityContextAsync 时，可以使用身份验证机构验证入站凭据。 如果此类颁发机构不可用，函数将失败并返回 SEC_E_NO_AUTHENTICATING_AUTHORITY。 验证特定于包。 |
| SECPKG_CRED_OUTBOUND | 允许本地客户端凭据准备传出令牌。 |
pvLogonId
指向 本地唯一标识符 的指针 (标识用户的 LUID) 。 此参数为网络重定向程序等文件系统进程提供。 此参数可以为 NULL。
pAuthData
指向 CREDSSP_CRED 结构的指针，该结构指定 Schannel 和 Negotiate 包的身份验证数据。
pGetKeyFn
指向 GetKey () 函数的指针。
pvGetKeyArgument
传递给 GetKey () 。
phCredential
指向将接收凭据句柄 的 CredHandle 结构的指针。
ptsExpiry
选 指向 TimeStamp 结构的指针，该结构接收返回的凭据过期的时间。 收到的结构值取决于安全包，安全包必须指定本地时间的值。
返回值
如果获取凭据句柄的异步请求已成功排队等待执行，则返回 SEC_E_OK 。 否则，它将返回尝试将其排队时生成的错误。 若要检索操作的状态，请使用 SspiGetAsyncCallStatus。
如果获取句柄，SspiGetAsyncCallStatus 将返回 SEC_E_OK。 否则，如果调用仍在进行中，则可能会返回 SEC_I_ASYNC_CALL_PENDING ，或者下表中存在以下任一致命错误代码。
返回代码 |
说明 |
|---|---|
| SEC_E_INSUFFICIENT_MEMORY | 内存不足，无法完成请求的操作。 |
| SEC_E_INTERNAL_ERROR | 发生了未映射到 SSPI 错误代码的错误。 |
| SEC_E_NO_CREDENTIALS | 安全包中没有可用的凭据 |
| SEC_E_NOT_OWNER | 函数的调用方没有所需的凭据。 |
| SEC_E_SECPKG_NOT_FOUND | 请求的安全包不存在。 |
| SEC_E_UNKNOWN_CREDENTIALS | 无法识别提供给包的凭据。 |
注解
SspiAcquireCredentialsHandleAsyncW 函数返回由特定安全包使用的主体（例如用户或客户端）凭据的句柄。 函数可以将句柄返回到预先存在的凭据或新创建的凭据，并返回它。 此句柄可用于后续调用 SspiAcceptSecurityContextAsync 和 SspiInitializeSecurityContextAsync 函数。
通常， SspiAcquireCredentialsHandleAsyncW 不提供登录到同一计算机的其他用户的凭据。 但是，具有SE_TCB_NAME特权的调用方可以通过指定该会话的 LUID) 登录标识符 (来获取现有登录会话的凭据。 通常，这由必须代表登录用户的内核模式模块使用。
包可能会调用 RPC 运行时传输提供的 pGetKeyFn 中的函数。 如果传输不支持用于检索凭据的回调概念，则此参数必须为 NULL。
对于内核模式调用方，必须指出以下差异：
- 这两个字符串参数必须是 Unicode 字符串。
- 缓冲区值必须在进程虚拟内存中分配，而不是从池中分配。
使用完返回的凭据后，通过调用 SspiFreeCredentialsHandleAsync 函数释放凭据使用的内存。
要求
| 最低受支持的客户端 | Windows 10版本 1607 [仅限内核模式驱动程序] |
| 最低受支持的服务器 | Windows Server 2016 [仅限内核模式驱动程序] |
| 标头 | sspi.h |
另请参阅
SspiAcceptSecurityContextAsync
SspiFreeCredentialsHandleAsync