AcquireCredentialsHandle （Schannel）函数

AcquireCredentialsHandle （Schannel） 函数获取一个用于预先存在的安全主体凭据的句柄。 InitializeSecurityContext（Schannel）和 AcceptSecurityContext （Schannel）函数需要此句柄。这些凭据可以是预先存在的凭据，这些凭据是通过此处未描述的系统登录建立的，或者调用方可以提供替代凭据。

注释

这不是“登录到网络”，也不意味着收集凭据。

语法

SECURITY_STATUS SEC_Entry AcquireCredentialsHandle(
  _In_opt_  SEC_CHAR       *pszPrincipal,
  _In_      SEC_CHAR       *pszPackage,
  _In_      ULONG          fCredentialUse,
  _In_opt_  PLUID          pvLogonID,
  _In_opt_  PVOID          pAuthData,
  _In_opt_  SEC_GET_KEY_FN pGetKeyFn,
  _In_opt_  PVOID          pvGetKeyArgument,
  _Out_     PCredHandle    phCredential,
  _Out_opt_ PTimeStamp     ptsExpiry
);

参数

pszPrincipal[in, optional]

指向以 null 结尾的字符串的指针，该字符串指定其句柄将引用其凭据的主体的名称。

使用 Schannel SSP 时，此参数不使用，应设置为 NULL。

注释

如果请求句柄的进程无权访问凭据，该函数将返回错误。 null 字符串指示进程需要对其正在执行的安全上下文的用户凭据的句柄。

pszPackage[in]

指向以 null 结尾的字符串的指针，该字符串指定使用这些凭据的安全包的名称。这是 EnumerateSecurityPackages 函数返回的 SecPkgInfo 结构的 Name 成员中返回的安全包名称。建立上下文后，可以使用 ulAttribute 设置为SECPKG_ATTR_PACKAGE_INFO调用 QueryContextAttributes （Schannel），以返回有关正在使用的安全包的信息。

使用 Schannel SSP 时，请将此参数设置为 UNISP_NAME.

注释

调用 AcquireCredentialsHandle（Schannel）后调用 InitializeSecurityContext （Schannel）时遇到问题的内核模式调用方也可以将 pszPackage 设置为 SCHANNEL_NAME。

fCredentialUse[in]

指示如何使用这些凭据的标志。此参数可以是下列值之一。

价值	含义
SECPKG_CRED_INBOUND	验证传入的服务器凭据。调用 InitializeSecurityContext（Schannel）或 AcceptSecurityContext（Schannel）时，可以使用身份验证机构验证入站凭据。如果此类颁发机构不可用，该函数将失败并返回 SEC_E_NO_AUTHENTICATING_AUTHORITY。验证特定于包。
SECPKG_CRED_OUTBOUND	允许本地客户端凭据准备传出令牌。

pvLogonID[in, optional]

指向标识用户的本地唯一标识符（LUID）的指针。为文件系统进程（如网络重定向程序）提供此参数。此参数可以是 NULL.

使用 Schannel SSP 时，此参数不使用，应设置为 NULL。

pAuthData[in, optional]

指向特定于包的数据的指针。此参数可以 NULL指示必须使用该安全包的默认凭据。若要使用提供的凭据，请传递包含此参数中的凭据的SEC_WINNT_AUTH_IDENTITY 结构。 RPC 运行时会传递 RpcBindingSetAuthInfo 中提供的任何内容。

使用 Schannel SSP 时，指定一个 SCH_CREDENTIALS 结构，该结构指示要使用的协议以及各种可自定义通道功能的设置。

pGetKeyFn[in, optional]

此参数未使用，应设置为 NULL。

pvGetKeyArgument[in, optional]

此参数未使用，应设置为 NULL。

phCredential[out]

指向 CredHandle 结构的指针，用于接收凭据句柄。

ptsExpiry[out, optional]

指向 TimeStamp 结构的指针，该结构接收返回的凭据过期的时间。此 TimeStamp 结构中返回的值取决于约束委派。安全包必须在本地时间返回此值。

使用 Schannel SSP 时，此参数是可选的。当用于身份验证的凭据是证书时，此参数将接收该证书的过期时间。如果未提供证书，则返回最大时间值。

返回值

如果函数成功，该函数将 SEC_E_OK返回。

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

返回代码	说明
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	无法识别提供给包的凭据。

注解

AcquireCredentialsHandle （Schannel） 函数返回主体的凭据（如用户或客户端）的句柄，如特定约束委派使用。这可以是预先存在的凭据的句柄，或者该函数可以创建一组新的凭据并返回它。此句柄可用于对 AcceptSecurityContext （Schannel）和 InitializeSecurityContext （Schannel）函数的后续调用。

通常， AcquireCredentialsHandle （Schannel） 不允许进程获取登录到同一计算机的其他用户的凭据的句柄。但是，具有 SE_TCB_NAME权限的调用方可以选择指定任何现有登录会话令牌的登录标识符（LUID），以获取该会话凭据的句柄。这通常由内核模式模块使用，这些模块必须代表已登录用户执行作。

包可能会调用 RPC 运行时传输提供的 pGetKeyFn 中的函数。如果传输不支持用于检索凭据的回调概念，则此参数必须为 NULL。

对于内核模式调用方，必须注意以下差异：

这两个字符串参数必须是 Unicode 字符串。
缓冲区值必须在进程虚拟内存中分配，而不是从池分配。

使用返回的凭据完成后，通过调用 FreeCredentialsHandle 函数释放凭据使用的内存。

要求

要求	价值
支持的最低客户端	Windows XP [仅限桌面应用]
支持的最低服务器	Windows Server 2003 [仅限桌面应用]
标题	Sspi.h（包括 Security.h）
图书馆	Secur32.lib
DLL	Secur32.dll
Unicode 和 ANSI 名称	AcquireCredentialsHandleW （Unicode）和 AcquireCredentialsHandleA （ANSI）