AcquireCredentialsHandle (Negotiate) 函数

项目
06/13/2023

AcquireCredentialsHandle (Negotiate) 函数获取安全主体的预先存在的凭据的句柄。 InitializeSecurityContext (Negotiate) 和 AcceptSecurityContext (Negotiate) 函数需要此句柄。这些凭据可以是预先存在的凭据，这些凭据是通过此处未介绍的系统登录建立的，也可以是调用方可以提供替代凭据。

注意

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

语法

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

注意

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

pszPackage [in]

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

若要使用 Negotiate SSP 成功调用此函数，请将此参数设置为“Negotiate”。

fCredentialUse [in]

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

值	含义
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	安全性不使用默认登录凭据或凭据管理器中的凭据。 Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不支持此值。
SECPKG_CRED_BOTH	验证传入凭据或使用本地凭据准备传出令牌。此标志启用其他两个标志。
SECPKG_CRED_INBOUND	验证传入服务器凭据。调用 InitializeSecurityContext (协商) 或 AcceptSecurityContext 时，可以使用身份验证机构验证入站凭据， (协商) 。如果此类颁发机构不可用，函数将失败并返回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。

pAuthData [in]

指向包特定数据的指针。此参数可以为 NULL，表示必须使用该 安全包 的默认凭据。若要使用提供的凭据，请将上一次调用返回 的 PSEC_WINNT_AUTH_IDENTITY_OPAQUE 结构传递给 SspiPromptForCredentials 函数。

Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP：不支持 PSEC_WINNT_AUTH_IDENTITY_OPAQUE 类型和 SspiPromptForCredentials 函数。若要使用提供的凭据，请传递指向包含这些凭据 的SEC_WINNT_AUTH_IDENTITY 或 SEC_WINNT_AUTH_IDENTITY_EX 结构的指针。

RPC 运行时间超过 RpcBindingSetAuthInfo 中提供的任何时间。

使用 Negotiate 包时，用户名、密码和域的最大字符长度分别为 256、256 和 15。

pGetKeyFn [in]

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

pvGetKeyArgument [in]

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

phCredential [out]

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

ptsExpiry [out]

指向 TimeStamp 结构的指针，该结构接收返回的凭据过期的时间。此 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 (Negotiate) 函数返回由特定约束委派使用的主体（如用户或客户端）凭据的句柄。这可以是预先存在的凭据的句柄，或者函数可以创建一组新的凭据并返回它。此句柄可用于后续调用 AcceptSecurityContext (Negotiate) 和 InitializeSecurityContext (Negotiate) 函数。

通常， AcquireCredentialsHandle (Negotiate) 不允许进程获取登录到同一计算机的其他用户凭据的句柄。但是，具有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)

另请参阅

SSPI 函数
AcceptSecurityContext (Negotiate)
InitializeSecurityContext (协商)
FreeCredentialsHandle

通过

AcquireCredentialsHandle (Negotiate) 函数

语法

parameters

返回值

备注

要求

另请参阅

反馈

其他资源