The asynchronous SSPI header includes functions that support async context objects, allowing callers to establish security contexts between server and remote clients concurrently through an async SSPI call lifecycle.
Async context management types
| Object Name | Description |
|---|---|
| SspiAsyncNotifyCallback | Callback used for notifying completion of an async SSPI call. |
Async context management functions
| API Name | Description |
|---|---|
| SspiCreateAsyncContext | Creates an instance of SspiAsyncContext which is used to track the async call. |
| SspiReinitAsyncContext | Marks an async context for reuse. |
| SspiSetAsyncNotifyCallback | Registers a callback that is notified on async call completion. |
| SspiAsyncContextRequiresNotify | Determines whether a given async context requires notification on completion of the call. |
| SspiGetAsyncCallStatus | Gets the current status of an async call associated with the provided context. |
| SspiFreeAsyncContext | Frees up a context created in the call to the SspiCreateAsyncContext function. |
Async SSPI functions
The following functions accept an async context in addition to all the same parameters as their synchronous counterpart.
| API Name | Description |
|---|---|
| SspiAcquireCredentialsHandleAsync | Asynchronously acquires a handle to preexisting credentials of a security principal. |
| SspiAcceptSecurityContextAsync | Lets the server component of a transport application asynchronously establish a security context between the server and a remote client. |
| SspiInitializeSecurityContextAsync | Initializes an async security context. |
| SspiDeleteSecurityContextAsync | Deletes the local data structures associated with the specified security context initiated by a previous call to the SspiInitializeSecurityContextAsync function or the SspiAcceptSecurityContextAsync function. |
| SspiFreeCredentialsHandleAsync | Frees up a credential handle. |
API Sample
A typical call flow works as follows:
- Create SspiAsyncContext context to track call using SspiCreateAsyncContext
- Register an SspiAsyncNotifyCallback for the context
- Make the async call using SspiAcceptSecurityContextAsync
- On callback, retrieve the result using SspiGetAsyncCallStatus
- Delete SspiAsyncContext using SspiDeleteSecurityContextAsync. If reusing the context with SspiReinitAsyncContext, go back to step 2.
The sample below demonstrates an invocation of SspiAcceptSecurityContextAsync. The sample waits for the call to complete and retrieves the result.
In a full SSPI handshake, SspiAcceptSecurityContextAsync and SspiInitializeSecurityContextAsync would be called multiple times until SEC_E_OK is returned. SspiReinitAsyncContext has been provided for ease of use and to facilitate performance in this case.
Asserts are used to highlight what we would expect in the case of success.
#include <sspi.h>
void AsyncCallCompleted(
_In_ SspiAsyncContext* AsyncContext,
_In_opt_ PVOID pCallbackData
)
{
// Get result.
SECURITY_STATUS Status = SspiGetAsyncCallStatus(AsyncContext);
ASSERT(SEC_E_OK == Status);
// *Perform any needed callback actions, use pCallbackData if needed*
// Clean up async context when done.
SspiFreeAsyncContext(AsyncContext);
}
void DoASCCall(
_In_opt_ PCredHandle phCred,
_In_opt_ PCtxtHandle phContext,
_In_opt_ PSecBufferDesc pInput,
_In_opt_ PSecBufferDesc pOutput,
_Out_ unsigned long* pfContextAttr,
_Out_opt_ PTimeStamp ptsExpiry
)
{
// Create context for async call
SspiAsyncContext* AsyncContext = SspiCreateAsyncContext();
// Check for out of memory condition
ASSERT(AsyncContext);
// Register callback that continues execution upon completion.
PVOID pCallbackData = … ; // *Setup any state needed for callback.*
SECURITY_STATUS Status = SspiSetAsyncNotifyCallback(AsyncContext,
AsyncCallCompleted,
pCallbackData);
ASSERT(SEC_E_OK == Status);
// Queue asynchronous call.
Status = SspiAcceptSecurityContextAsync(AsyncContext,
phCred,
phContext,
pInput,
ASC_REQ_CONNECTION,
SECURITY_NATIVE_DREP,
phContext,
pOutput,
pfContextAttr,
ptsExpiry);
// All async functions return the status of queueing the async call,
// not the call’s result.
ASSERT(SEC_E_OK == Status);
// At this point, the call can be pending or complete.
// If complete, the result or error is returned.
// For this example, we assume if it finished, it finished with SEC_E_OK.
Status = SspiGetAsyncCallStatus(AsyncContext);
ASSERT(SEC_I_ASYNC_CALL_PENDING == Status ||
SEC_E_OK == Status);
// Execution will continue in the callback upon completion
}
See Also
Source: Microsoft Learn / Windows Win32 documentation by Microsoft and contributors. Documentation licensed CC BY 4.0. Code samples are covered by the MIT License. Converted from Markdown, with links normalized and embedded media omitted.
