AcquireCredentialsHandleA 函数 (sspi.h)
AcquireCredentialsHandle (CredSSP) 函数获取安全主体的预先存在的凭据的句柄。 InitializeSecurityContext (CredSSP) 和 AcceptSecurityContext (CredSSP) 函数需要此句柄。 这些凭据可以是预先存在的凭据，这些 凭据是通过此处未介绍的系统登录建立的，也可以是调用方可以提供替代凭据。
语法
SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA(
[in, optional] LPSTR pszPrincipal,
[in] LPSTR pszPackage,
[in] unsigned long fCredentialUse,
[in, optional] void *pvLogonId,
[in, optional] void *pAuthData,
[in, optional] SEC_GET_KEY_FN pGetKeyFn,
[in, optional] void *pvGetKeyArgument,
[out] PCredHandle phCredential,
[out, optional] PTimeStamp ptsExpiry
);
参数
[in, optional] pszPrincipal
指向以 null 结尾的字符串的指针，该字符串指定句柄将引用其凭据的主体的名称。
[in] pszPackage
指向以 null 结尾的字符串的指针，该字符串指定要使用这些凭据 的安全包 的名称。 这是 EnumerateSecurityPackages 函数返回的 SecPkgInfo 结构的 Name 成员中返回的安全包名称。 建立上下文后，可以在将 ulAttribute 设置为 SECPKG_ATTR_PACKAGE_INFO 的情况下调用 QueryContextAttributes (CredSSP) ，以返回有关正在使用的安全包的信息。
[in] fCredentialUse
指示如何使用这些凭据的标志。 此参数的取值可为下列值之一：
| 值 | 含义 |
|---|---|
|
验证传入服务器凭据。 调用 InitializeSecurityContext (CredSSP) 或 AcceptSecurityContext (CredSSP) 时，可以使用身份验证机构验证入站凭据。 如果此类颁发机构不可用，该函数将失败并返回 SEC_E_NO_AUTHENTICATING_AUTHORITY。 验证特定于包。 |
|
允许本地客户端凭据准备传出令牌。 |
[in, optional] pvLogonId
指向标识用户的 LUID) 本地唯一标识符 (指针。 此参数是为网络重定向程序等文件系统进程提供的。 此参数可以为 NULL。
[in, optional] pAuthData
指向 CREDSSP_CRED 结构的指针，该结构指定 Schannel 和 Negotiate 包的身份验证数据。
[in, optional] pGetKeyFn
保留。 此参数未使用，应设置为 NULL。
[in, optional] pvGetKeyArgument
保留。 此参数必须设置为 NULL。
[out] phCredential
指向将接收凭据句柄的 CredHandle 结构的指针。
[out, optional] ptsExpiry
指向 TimeStamp 结构的指针，该结构接收返回的凭据的过期时间。 接收的结构值取决于安全包，安全包必须指定本地时间的值。
返回值
如果该函数成功，则返回 SEC_E_OK。
如果该函数失败，它将返回以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
可用内存不足，无法完成请求的操作。 |
|
发生了未映射到 SSPI 错误代码的错误。 |
|
安全包中没有可用的凭据。 |
|
函数的调用方没有所需的凭据。 |
|
请求的安全包不存在。 |
|
无法识别提供给包的凭据。 |
注解
AcquireCredentialsHandle (CredSSP) 函数返回特定安全包使用的主体（如用户或客户端）凭据的句柄。 函数可以将句柄返回到预先存在的凭据或新创建的凭据，并返回它。 此句柄可用于后续调用 AcceptSecurityContext (CredSSP) 和 InitializeSecurityContext (CredSSP) 函数。
通常， AcquireCredentialsHandle (CredSSP) 不提供登录到同一计算机的其他用户的凭据。 但是，具有SE_TCB_NAME特权的调用方可以通过指定该会话的登录标识符 (LUID) 来获取现有登录会话的凭据。 通常，这由必须代表已登录用户的内核模式模块使用。
包可能会调用 RPC 运行时传输提供的 pGetKeyFn 中的函数。 如果传输不支持用于检索凭据的回调概念，则此参数必须为 NULL。
对于内核模式调用方，必须注意到以下差异：
- 这两个字符串参数必须是 Unicode 字符串。
- 缓冲区值必须在进程虚拟内存中分配，而不是从池中分配。
注意
sspi.h 标头将 AcquireCredentialsHandle 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。
要求
| 最低受支持的客户端 | Windows Vista [仅限桌面应用] |
| 最低受支持的服务器 | Windows Server 2008 [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | sspi.h (包括 Security.h) |
| Library | Secur32.lib |
| DLL | Secur32.dll |
另请参阅
AcceptSecurityContext (CredSSP)