大网数据广告活动
账户与安全

Asynchronous SSPI

· 52CE 我爱测

Overview of the asynchronous SSPI header.

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:

  1. Create SspiAsyncContext context to track call using SspiCreateAsyncContext
  2. Register an SspiAsyncNotifyCallback for the context
  3. Make the async call using SspiAcceptSecurityContextAsync
  4. On callback, retrieve the result using SspiGetAsyncCallStatus
  5. 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

sspi.h header

SSPI functions

SSPI structures

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.

资料来源与适用范围

资料来源
Microsoft Learn / Windows Win32 documentation
适用范围
Windows Win32 API · Source date 06/23/2020
内容语言
中文;命令、路径和错误标识保留技术原文
本地收录日期
2026-11-15
授权说明
CC BY 4.0 (documentation), MIT (code samples)

正文与所需资源由本站本地存储。查看来源及更新记录 ↗

请按适用版本和实际日志确认原因;本站没有对每一种系统或设备逐项执行文中的操作。