AcquireCredentialsHandle

The AcquireCredentialsHandle function allows applications to acquire a handle to pre-existing credentials associated with the user on whose behalf the call is made. These pre-existing credentials are established through a system logon not described here.

Note that this is different from "login to the network" and does not imply gathering of credentials.

SECURITY_STATUS AcquireCredentialsHandle(
  SEC_CHAR * pszPrincipal,  // name of principal
  SEC_CHAR * pszPackage, // name of package
  ULONG fCredentialUse,  // flags indicating use
  PLUID pvLogonID,       // pointer to logon identifier
  PVOID pAuthData,       // package-specific data
  PVOID pGetKeyFn,       // pointer to GetKey function
  PVOID pvGetKeyArgument,  // value to pass to GetKey
  PCredHandle phCredential,  // credential handle
  PTimeStamp ptsExpiry   // life time of the returned credentials
);

Parameters

pszPrincipal
Pointer to a null-terminated string the 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
Pointer to a null-terminated string the 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
A flag that indicates how these credentials will be used. This parameter can one of the following values:

CRED_INBOUND
CRED_OUTBOUND
CRED_BOTH

The credentials created with the CRED_INBOUND option can be used only for validating incoming calls. They cannot be used for accessing objects.

pvLogonId
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
Pointer to package-specific data. This parameter can be NULL, indicating that the default credentials for that package should be used. The RPC run time passes whatever was provided in the RpcBindingSetAuthInfo function.
pGetKeyFn
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
Specifies the pointer argument that the security provider should pass to the GetKey function. This parameter can be NULL.
phCredential
Pointer to CredHandle structure that receives the credential handle.
ptsExpiry
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

If the function succeeds, the return value is SEC_E_OK.

If the function fails, the return value may be one of the following error codes.

Value Meaning
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.

If the caller is a system process with the SE_TCB_NAME privilege (for example, an FSP), and the caller provides both the name and logon identifier, the function verifies that they match before returning the credentials. If only one is provided, the function returns a handle to that identifier.

If the caller is not a system process, the caller can only obtain a handle to the credentials under which it is running The caller can provide the name or the logon identifier, but it must be for the current session or the request fails.

When you no longer need the returned credentials, call the FreeCredentialsHandle function.

See Also

FreeCredentialsHandle