AcquireCredentialsHandle (General) 函数
AcquireCredentialsHandle (常规) 函数获取安全主体的预先存在的凭据的句柄。 InitializeSecurityContext (General) 和 AcceptSecurityContext (General) 函数需要此句柄。 这些凭据可以是预先存在的凭据，这些凭据是通过此处未介绍的系统登录建立的，也可以是调用方可以提供替代凭据。
注意
这不是“登录到网络”，也不意味着收集凭据。
有关将此函数与特定 安全支持提供程序 (SSP) 配合使用的信息，请参阅以下主题。
| 主题 | 说明 |
|---|---|
| AcquireCredentialsHandle (CredSSP) |
获取使用凭据安全支持提供程序 (CredSSP) 的安全主体的预先存在的凭据的句柄。 |
| AcquireCredentialsHandle (Digest) |
获取使用 Digest 的安全主体的预先存在的凭据的句柄。 |
| AcquireCredentialsHandle (Kerberos) |
获取使用 Kerberos 的安全主体的预先存在凭据的句柄。 |
| AcquireCredentialsHandle (协商) |
获取使用 Negotiate 的安全主体的预先存在凭据的句柄。 |
| AcquireCredentialsHandle (NTLM) |
获取使用 NTLM 的安全主体的预先存在的凭据的句柄。 |
| AcquireCredentialsHandle (Schannel) |
获取使用 Schannel 的安全主体的预先存在的凭据的句柄。 |
语法
SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
_In_ SEC_CHAR *pszPrincipal,
_In_ SEC_CHAR *pszPackage,
_In_ ULONG fCredentialUse,
_In_ PLUID pvLogonID,
_In_ PVOID pAuthData,
_In_ SEC_GET_KEY_FN pGetKeyFn,
_In_ PVOID pvGetKeyArgument,
_Out_ PCredHandle phCredential,
_Out_ PTimeStamp ptsExpiry
);
parameters
-
pszPrincipal [in]
-
指向以 null 结尾的字符串的指针，该字符串指定句柄将引用其凭据的主体的名称。
使用摘要 SSP 时，此参数是可选的。
使用 Schannel SSP 时，不使用此参数，应设置为 NULL。
注意
如果请求句柄的进程无权访问凭据，则函数将返回错误。 null 字符串指示进程需要对其 执行其安全上下文 的用户凭据的句柄。
-
pszPackage [in]
-
指向以 null 结尾的字符串的指针，该字符串指定要使用这些凭据 的安全包 的名称。 这是在 EnumerateSecurityPackages 函数返回的 SecPkgInfo 结构的 Name 成员中返回的安全包名称。 建立上下文后，可以使用 ulAttribute 设置为 SECPKG_ATTR_PACKAGE_INFO 调用 QueryContextAttributes (General ) ，以返回有关正在使用的安全包的信息。
使用摘要 SSP 时，请将此参数设置为 WDIGEST_SP_NAME。
使用 Schannel SSP 时，请将此参数设置为 UNISP_NAME。
-
fCredentialUse [in]
-
指示如何使用这些凭据的标志。 此参数的取值可为下列值之一：
值 含义 - SECPKG_CRED_AUTOLOGON_RESTRICTED
- 0x00000010
安全性不使用默认登录凭据或 凭据管理器中的凭据。
此值仅受协商 约束委派支持。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此值。- SECPKG_CRED_BOTH
验证传入凭据或使用本地凭据准备传出令牌。 此标志启用其他两个标志。 此标志在摘要和 Schannel SSP 中无效。 - SECPKG_CRED_INBOUND
验证传入服务器凭据。 调用 InitializeSecurityContext (General) 或 AcceptSecurityContext (General) 时，可以使用身份验证机构验证入站凭据。 如果此类颁发机构不可用，函数将失败并返回SEC_E_NO_AUTHENTICATING_AUTHORITY。 验证特定于包。 - SECPKG_CRED_OUTBOUND
允许本地客户端凭据准备传出令牌。 - SECPKG_CRED_PROCESS_POLICY_ONLY
- 0x00000020
函数处理服务器策略并返回 SEC_E_NO_CREDENTIALS，指示应用程序应提示输入凭据。
此值仅受协商 约束委派支持。
Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP： 不支持此值。 -
pvLogonID [in]
-
指向 本地唯一标识符 的指针 (标识用户的 LUID) 。 此参数为网络重定向程序等文件系统进程提供。 此参数可以为 NULL。
使用 Schannel SSP 时，不使用此参数，应设置为 NULL。
-
pAuthData [in]
-
指向包特定数据的指针。 此参数可以为 NULL，表示必须使用该 安全包 的默认凭据。 若要使用提供的凭据，请传递一个 SEC_WINNT_AUTH_IDENTITY 结构，该结构在此参数中包含这些凭据。 RPC 运行时间超过 RpcBindingSetAuthInfo 中提供的任何时间。
使用摘要 SSP 时，此参数是指向包含用于查找凭据的身份验证信息的 SEC_WINNT_AUTH_IDENTITY 结构的指针。
使用 Schannel SSP 时，请指定 一个SCHANNEL_CRED 结构，该结构指示要使用的协议以及各种可自定义通道功能的设置。
使用 NTLM 或 Negotiate 包时，用户名、密码和域的最大字符长度分别为 256、256 和 15。
-
pGetKeyFn [in]
-
此参数未使用，应设置为 NULL。
-
pvGetKeyArgument [in]
-
此参数未使用，应设置为 NULL。
-
phCredential [out]
-
指向 CredHandle 结构的指针，用于接收凭据句柄。
-
ptsExpiry [out]
-
指向 TimeStamp 结构的指针，该结构接收返回的凭据过期的时间。 此 TimeStamp 结构中返回的值取决于 约束委派。 安全包必须以本地时间返回此值。
此参数设置为恒定的最长时间。 摘要 安全上下文或凭据在使用摘要 SSP 时没有过期时间。
使用 Schannel SSP 时，此参数是可选的。 当用于身份验证的凭据是证书时，此参数接收该证书的过期时间。 如果未提供证书，则返回最大时间值。
返回值
如果该函数成功，则函数返回SEC_E_OK。
如果函数失败，它将返回以下错误代码之一。
| 返回代码 | 说明 |
|---|---|
|
没有足够的内存可用于完成请求的操作。 |
|
发生了未映射到 SSPI 错误代码的错误。 |
|
约束委派中没有可用的凭据。 |
|
函数的调用方没有所需的凭据。 |
|
请求 的安全包 不存在。 |
|
无法识别提供给包的凭据。 |
备注
AcquireCredentialsHandle (General) 函数返回由特定约束委派使用的主体（如用户或客户端）凭据的句柄。 这可以是预先存在的凭据的句柄，或者函数可以创建一组新的凭据并返回它。 此句柄可用于后续调用 AcceptSecurityContext (General) 和 InitializeSecurityContext (General) 函数。
通常， AcquireCredentialsHandle (常规) 不允许进程获取登录到同一计算机的其他用户的凭据的句柄。 但是，具有SE_TCB_NAME 特权 的调用方可以选择指定 任何现有登录 会话令牌 (LUID) 登录标识符，以获取该会话凭据的句柄。 通常，这由必须代表已登录用户的内核模式模块使用。
包可能会调用 RPC 运行时传输提供的 pGetKeyFn 中的函数。 如果传输不支持用于检索凭据的回调概念，则此参数必须为 NULL。
对于内核模式调用方，必须注意到以下差异：
- 这两个字符串参数必须是 Unicode 字符串。
- 缓冲区值必须在进程虚拟内存中分配，而不是从池中分配。
使用完返回的凭据后，通过调用 FreeCredentialsHandle 函数释放凭据使用的内存。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 |
Windows XP [仅限桌面应用] |
| 最低受支持的服务器 |
Windows Server 2003 [仅限桌面应用] |
| 标头 |
|
| 库 |
|
| DLL |
|
| Unicode 和 ANSI 名称 |
AcquireCredentialsHandleW (Unicode) 和 AcquireCredentialsHandleA (ANSI) |
另请参阅
反馈
即将发布：在整个 2024 年，我们将逐步淘汰作为内容反馈机制的“GitHub 问题”，并将其取代为新的反馈系统。 有关详细信息，请参阅：https://aka.ms/ContentUserFeedback。
提交和查看相关反馈