AcquireCredentialsHandleA function (sspi.h)
The AcquireCredentialsHandle (CredSSP) function acquires a handle to preexisting credentials of a security principal. This handle is required by the InitializeSecurityContext (CredSSP) and AcceptSecurityContext (CredSSP) 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.
SECURITY_STATUS SEC_ENTRY AcquireCredentialsHandleA( [in, optional] LPSTR pszPrincipal, [in] LPSTR pszPackage, [in] unsigned long fCredentialUse, [in, optional] void *pvLogonId, [in, optional] void *pAuthData, [in, optional] SEC_GET_KEY_FN pGetKeyFn, [in, optional] void *pvGetKeyArgument, [out] PCredHandle phCredential, [out, optional] PTimeStamp ptsExpiry );
[in, optional] pszPrincipal
A pointer to a null-terminated string that specifies the name of the principal whose credentials the handle will reference.
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 (CredSSP) can be called with ulAttribute set to SECPKG_ATTR_PACKAGE_INFO to return information on the security package in use.
A flag that indicates how these credentials will be used. This parameter can be one of the following values.
||Validate an incoming server credential. Inbound credentials might be validated by using an authenticating authority when InitializeSecurityContext (CredSSP) or AcceptSecurityContext (CredSSP) is called. If such an authority is not available, the function will fail and return SEC_E_NO_AUTHENTICATING_AUTHORITY. Validation is package specific.|
||Allow a local client credential to prepare an outgoing token.|
[in, optional] pvLogonId
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.
[in, optional] pAuthData
A pointer to a CREDSSP_CRED structure that specifies authentication data for both Schannel and Negotiate packages.
[in, optional] pGetKeyFn
Reserved. This parameter is not used and should be set to NULL.
[in, optional] pvGetKeyArgument
Reserved. This parameter must be set to NULL.
A pointer to the CredHandle structure that will receive the credential handle.
[out, optional] ptsExpiry
A pointer to a TimeStamp structure that receives the time at which the returned credentials expire. The structure value received depends on the security package, which must specify the value in local time.
If the function succeeds, it returns SEC_E_OK.
If the function fails, it returns one of the following error codes.
||There is insufficient memory available to complete the requested action.|
||An error occurred that did not map to an SSPI error code.|
||No credentials are available in the security package.|
||The caller of the function does not have the necessary credentials.|
||The requested security package does not exist.|
||The credentials supplied to the package were not recognized.|
The AcquireCredentialsHandle (CredSSP) function returns a handle to the credentials of a principal, such as a user or client, as used by a specific security package. The function can return the handle to either preexisting credentials or newly created credentials and return it. This handle can be used in subsequent calls to the AcceptSecurityContext (CredSSP) and InitializeSecurityContext (CredSSP) functions.
In general, AcquireCredentialsHandle (CredSSP) does not provide the credentials of other users logged on to the same computer. However, a caller with SE_TCB_NAME privilege can obtain the credentials of an existing logon session by specifying the logon identifier (LUID) of that session. 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.
The sspi.h header defines AcquireCredentialsHandle as an alias which automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
|Minimum supported client||Windows Vista [desktop apps only]|
|Minimum supported server||Windows Server 2008 [desktop apps only]|
|Header||sspi.h (include Security.h)|