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
);
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.
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. |
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.