AcquireCredentialsHandle (General) function

The AcquireCredentialsHandle (General) function acquires a handle to preexisting credentials of a security principal. This handle is required by the InitializeSecurityContext (General) and AcceptSecurityContext (General) functions. These can be either preexisting credentials, which are established through a system logon that is not described here, or the caller can provide alternative credentials.

For information about using this function with a specific security support provider (SSP), see the following topics.

Syntax

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]

A pointer to a null-terminated string that specifies the name of the principal whose credentials the handle will reference.

When using the Digest SSP, this parameter is optional.

When using the Schannel SSP, this parameter is not used and should be set to NULL.

Note

If the process that requests the handle does not have access to the credentials, the function returns an error. A null string indicates that the process requires a handle to the credentials of the user under whose security context it is executing.

 

pszPackage [in]

A pointer to a null-terminated string that specifies the name of the security package with which these credentials will be used. This is a security package name returned in the Name member of a SecPkgInfo structure returned by the EnumerateSecurityPackages function. After a context is established, QueryContextAttributes (General) can be called with ulAttribute set to SECPKG_ATTR_PACKAGE_INFO to return information on the security package in use.

When using the Digest SSP, set this parameter to WDIGEST_SP_NAME.

When using the Schannel SSP, set this parameter to UNISP_NAME.

fCredentialUse [in]

A flag that indicates how these credentials will be used. This parameter can be one of the following values.

Value	Meaning
SECPKG_CRED_AUTOLOGON_RESTRICTED 0x00000010	The security does not use default logon credentials or credentials from Credential Manager. This value is supported only by the Negotiate constrained delegation. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported.
SECPKG_CRED_BOTH	Validate an incoming credential or use a local credential to prepare an outgoing token. This flag enables both other flags. This flag is not valid with the Digest and Schannel SSPs.
SECPKG_CRED_INBOUND	Validate an incoming server credential. Inbound credentials might be validated by using an authenticating authority when InitializeSecurityContext (General) or AcceptSecurityContext (General) is called. If such an authority is not available, the function will fail and return SEC_E_NO_AUTHENTICATING_AUTHORITY. Validation is package specific.
SECPKG_CRED_OUTBOUND	Allow a local client credential to prepare an outgoing token.
SECPKG_CRED_PROCESS_POLICY_ONLY 0x00000020	The function processes server policy and returns SEC_E_NO_CREDENTIALS, indicating that the application should prompt for credentials. This value is supported only by the Negotiate constrained delegation. Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP: This value is not supported.

 

pvLogonID [in]

A pointer to a locally unique identifier (LUID) that identifies the user. This parameter is provided for file-system processes such as network redirectors. This parameter can be NULL.

When using the Schannel SSP, this parameter is not used and should be set to NULL.

pAuthData [in]

A pointer to package-specific data. This parameter can be NULL, which indicates that the default credentials for that security package must be used. To use supplied credentials, pass a SEC_WINNT_AUTH_IDENTITY structure that includes those credentials in this parameter. The RPC run time passes whatever was provided in RpcBindingSetAuthInfo.

When using the Digest SSP, this parameter is a pointer to a SEC_WINNT_AUTH_IDENTITY structure that contains authentication information to use to locate the credentials.

When using the Schannel SSP, specify an SCHANNEL_CRED structure that indicates the protocol to use and the settings for various customizable channel features.

When using the NTLM or Negotiate packages, the maximum character lengths for user name, password, and domain are 256, 256, and 15, respectively.

pGetKeyFn [in]

This parameter is not used and should be set to NULL.

pvGetKeyArgument [in]

This parameter is not used and should be set to NULL.

phCredential [out]

A pointer to a CredHandle structure to receive the credential handle.

ptsExpiry [out]

A pointer to a TimeStamp structure that receives the time at which the returned credentials expire. The value returned in this TimeStamp structure depends on the constrained delegation. The security package must return this value in local time.

This parameter is set to a constant maximum time. There is no expiration time for Digest security contexts or credentials or when using the Digest SSP.

When using the Schannel SSP, this parameter is optional. When the credential to be used for authentication is a certificate, this parameter receives the expiration time for that certificate. If no certificate was supplied, then a maximum time value is returned.

Return value

If the function succeeds, the function returns SEC_E_OK.

If the function fails, it returns one of the following error codes.

Remarks

The AcquireCredentialsHandle (General) function returns a handle to the credentials of a principal, such as a user or client, as used by a specific constrained delegation. This can be the handle to preexisting credentials, or the function can create a new set of credentials and return it. This handle can be used in subsequent calls to the AcceptSecurityContext (General) and InitializeSecurityContext (General) functions.

In general, AcquireCredentialsHandle (General) does not allow a process to obtain a handle to the credentials of other users logged on to the same computer. However, a caller with SE_TCB_NAME privilege has the option of specifying the logon identifier (LUID) of any existing logon session token to get a handle to that session's credentials. Typically, this is used by kernel-mode modules that must act on behalf of a logged-on user.

A package might call the function in pGetKeyFn provided by the RPC run-time transport. If the transport does not support the notion of callback to retrieve credentials, this parameter must be NULL.

For kernel mode callers, the following differences must be noted:

• The two string parameters must be Unicode strings.
• The buffer values must be allocated in process virtual memory, not from the pool.

When you have finished using the returned credentials, free the memory used by the credentials by calling the FreeCredentialsHandle function.

Requirements

See also

SSPI Functions

AcceptSecurityContext (General)

InitializeSecurityContext (General)

FreeCredentialsHandle