AcquireCredentialsHandle (CredSSP) 函数

AcquireCredentialsHandle (CredSSP) 函数获取安全主体的预先存在的凭据的句柄。 InitializeSecurityContext (CredSSP) AcceptSecurityContext (CredSSP) 函数需要此句柄。 这些凭据可以是预先存在的凭据,这些 凭据是通过此处未描述的系统登录建立的,或者调用方可以提供备用凭据。

注意

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

语法

SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandle(
  _In_opt_   SEC_CHAR       *pszPrincipal,
  _In_       SEC_CHAR       *pszPackage,
  _In_       unsigned long  fCredentialUse,
  _In_opt_   void           *pvLogonID,
  _In_opt_   void           *pAuthData,
  _In_opt_   SEC_GET_KEY_FN pGetKeyFn,
  _Reserved_ void           *pvGetKeyArgument,
  _Out_      PCredHandle    phCredential,
  _Out_opt_  PTimeStamp     ptsExpiry
);

parameters

pszPrincipal [in, 可选]

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

注意

如果请求句柄的进程无权访问凭据,该函数将返回错误。 空字符串表示进程需要处理其安全上下文下用户凭据的句柄。

pszPackage [in]

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

fCredentialUse [in]

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

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

pvLogonId [in, 可选]

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

pAuthData [in, 可选]

指向 CREDSSP_CRED 结构的指针,该结构指定 Schannel 和 Negotiate 包的身份验证数据。

pGetKeyFn [in, 可选]

保留。 此参数未使用,应设置为 NULL

pvGetKeyArgument [in, 可选]

保留。 此参数必须设置为 NULL

phCredential [out]

指向将接收凭据句柄的 CredHandle 结构的指针。

ptsExpiry [out, optional]

指向 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 函数释放凭据使用的内存。

要求

要求 “值”
最低受支持的客户端 Windows Vista [仅限桌面应用]
最低受支持的服务器 Windows Server 2008 [仅限桌面应用]
标头 Sspi.h (包括 Security.h)
Secur32.lib
DLL Secur32.dll
Unicode 和 ANSI 名称 AcquireCredentialsHandleW (Unicode) 和 AcquireCredentialsHandleA (ANSI)

另请参阅