通过

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 结尾的字符串的指针，该字符串指定其句柄将引用其凭据的主体的名称。

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

[in] pszPackage

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

[in] fCredentialUse

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

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

[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。

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

返回代码 描述
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 （CredSSP） 函数返回主体（例如用户或客户端）的句柄，如特定 安全包使用。 该函数可以将句柄返回到预先存在的凭据或新创建的凭据并返回该句柄。 此句柄可用于对 AcceptSecurityContext （CredSSP） 和 InitializeSecurityContext （CredSSP） 函数的后续调用。

通常，AcquireCredentialsHandle （CredSSP） 不提供登录到同一台计算机的其他用户的凭据。 但是，具有SE_TCB_NAME 特权 的调用方可以通过指定该会话的 登录标识符（LUID）来获取现有登录会话 的 凭据。 这通常由内核模式模块使用，这些模块必须代表已登录用户执行操作。

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

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

  • 两个字符串参数必须 Unicode 字符串。
  • 缓冲区值必须在进程虚拟内存中分配，而不是从池分配。
使用返回的凭据完成后，通过调用 FreeCredentialsHandle 函数释放凭据使用的内存。

注意

sspi.h 标头将 AcquireCredentialsHandle 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求 价值
最低支持的客户端 Windows Vista [仅限桌面应用]
支持的最低服务器 Windows Server 2008 [仅限桌面应用]
目标平台 窗户
标头 sspi.h （包括 Security.h）
库 Secur32.lib
DLL Secur32.dll

另请参阅

AcceptSecurityContext （CredSSP）

FreeCredentialsHandle

InitializeSecurityContext （CredSSP）

SSPI 函数