SspiAcquireCredentialsHandleAsyncA function (sspi.h)

Article
07/27/2022

The SspiAcquireCredentialsHandleAsyncA function asynchronously acquires a handle to preexisting credentials of a security principal.

This handle is required by the SspiInitializeSecurityContextAsync and SspiAcceptSecurityContextAsync 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.

Note

This function serves as the asynchronous counterpart to AcquireCredentialsHandle.

Syntax

SECURITY_STATUS SspiAcquireCredentialsHandleAsyncA(
  SspiAsyncContext *AsyncContext,
  LPSTR            pszPrincipal,
  LPSTR            pszPackage,
  unsigned long    fCredentialUse,
  void             *pvLogonId,
  void             *pAuthData,
  SEC_GET_KEY_FN   pGetKeyFn,
  void             *pvGetKeyArgument,
  PCredHandle      phCredential,
  PTimeStamp       ptsExpiry
);

Parameters

AsyncContext

The async call context.

pszPrincipal

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

pszPackage

A pointer to a null-terminated string that specifies the name of the security package with which these credentials will be used.

See AcquireCredentialsHandleA: pszPackage

fCredentialUse

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

Value	Meaning
SECPKG_CRED_INBOUND	Validate an incoming server credential. Inbound credentials might be validated by using an authenticating authority when SspiInitializeSecurityContextAsync or SspiAcceptSecurityContextAsync 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.

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.

pAuthData

A pointer to a CREDSSP_CRED structure that specifies authentication data for both Schannel and Negotiate packages.

pGetKeyFn

Pointer to the GetKey() function.

pvGetKeyArgument

Pass to GetKey().

phCredential

A pointer to the CredHandle structure that will receive the credential handle.

ptsExpiry

optional 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.

Return value

Returns SEC_E_OK if the async request to acquire a credential handle was successfully queued for execution. Otherwise, it returns the error generated attempting to queue it. To retrieve the status of the operation, use SspiGetAsyncCallStatus.

If the handle was acquired, SspiGetAsyncCallStatus returns SEC_E_OK. Otherwise, it may return SEC_I_ASYNC_CALL_PENDING if the call is still in progress, or any of the following fatal error codes in the table below.

Return code	Description
SEC_E_INSUFFICIENT_MEMORY	There is insufficient memory available to complete the requested action.
SEC_E_INTERNAL_ERROR	An error occurred that did not map to an SSPI error code.
SEC_E_NO_CREDENTIALS	No credentials are available in the security package
SEC_E_NOT_OWNER	The caller of the function does not have the necessary credentials.
SEC_E_SECPKG_NOT_FOUND	The requested security package does not exist.
SEC_E_UNKNOWN_CREDENTIALS	The credentials supplied to the package were not recognized.

Remarks

The SspiAcquireCredentialsHandleAsyncA 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 SspiAcceptSecurityContextAsync and SspiInitializeSecurityContextAsync functions.

In general, SspiAcquireCredentialsHandleAsyncA 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.

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

Requirements

Requirement	Value
Minimum supported client	Windows 10, version 1607 [kernel-mode drivers only]
Minimum supported server	Windows Server 2016 [kernel-mode drivers only]
Header	sspi.h