This function allows applications to acquire a handle to preexisting credentials associated with the user on whose behalf the call is made. These preexisting credentials are established through a system logon not described here. However, this is different from “login to the network” and does not imply gathering of credentials.
At a Glance
| Header file: | Sspi.h |
| Windows CE versions: | 2.10 and later |
Syntax
SECURITY_STATUS AcquireCredentialsHandle(
SEC_CHAR * pszPrincipal, SEC_CHAR * pszPackage,
ULONG fCredentialUse, PLUID pvLogonID, PVOID pAuthData,
PVOID pGetKeyFn, VOID pvGetKeyArgument, PCredHandle phCredential,
PTimeStamp ptsExpiry );
Parameters
pszPrincipal
[in] Pointer to a null-terminated string that specifies the name of the principal whose credentials the handle will reference. Note that if the process requesting 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] 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.
fCredentialUse
[in] Flag that indicates how these credentials will be used. This parameter can one of the following values:
The credentials created with the CRED_INBOUND option can be used only for validating incoming calls. They cannot be used for accessing objects.
pvLogonId
[in] Void pointer to a Windows NT–style logon identifier, an LUID. This parameter is provided for file-system processes such as network redirectors. This parameter can be NULL.
pAuthData
[in] Pointer to package-specific data. This parameter can be NULL, indicating that the default credentials for that package should be used. The NTLM SSP accepts a pointer to a SEC_WINNT_AUTH_IDENTITY structure, containing the user name, domain name and password.
pGetKeyFn
[in] Pointer to a SEC_GET_KEY_FN function to retrieve the key for the function. The security package can call this function, as provided by the RPC run-time transport application. This parameter can be NULL if the transport application does not support callbacks to retrieve credentials.
pvGetKeyArgument
[in] Specifies the pointer argument that the security provider should pass to the GetKey function. This parameter can be NULL.
phCredential
[out] Pointer to CredHandle structure that receives the credential handle.
ptsExpiry
[out] Pointer to a TimeStamp variable that receives the time at which the returned credentials expire. The value returned in this member depends on the security package. The security provider should always return this value in local time.
Return Values
SEC_E_OK indicates success.
Upon failure, one of the error values described in the following table is returned.
| Value | Description |
| SEC_E_UNKNOWN_CREDENTIALS | The credentials supplied to the package were not recognized. |
| SEC_E_NO_CREDENTIALS | No credentials are available in the security package. |
| SEC_E_NOT_OWNER | The caller of the function does not own the necessary credentials. |
| SEC_E_INSUFFICIENT_MEMORY | Not enough memory is available to complete this request. |
| SEC_E_INTERNAL_ERROR | The Local Security Authority cannot be contacted. |
| SEC_E_SECPKG_NOT_FOUND | The requested security package does not exist. |
Remarks
The AcquireCredentialsHandle function returns a handle to the credentials of a principal (user, client) as used by a specific security package. The handle returned can be used in subsequent calls to the AcceptSecurityContext and InitializeSecurityContext functions.
The AcquireCredentialsHandle function will not let a process obtain a handle to credentials that are not related to the process; in other words, a process cannot get the credentials of another user who is logged on to the same computer. There is no way to determine whether a process is a Trojan horse if it is executed by the user.
The AcquireCredentialsHandle function uses the following algorithm to determine whether to grant the request for a handle to the credentials.
When you no longer need the returned credentials, call the FreeCredentialsHandle function.
See Also