SspiAcceptSecurityContextAsync function (sspi.h)

Article
10/21/2021

The SspiAcceptSecurityContextAsync function lets the server component of a transport application asynchronously establish a security context between the server and a remote client. The remote client calls the SspiInitializeSecurityContextAsync function to asynchronously start the process of establishing a security context.

Note

This function serves as the asynchronous counterpart to theAcceptSecurityContext function.

Syntax

SECURITY_STATUS SspiAcceptSecurityContextAsync(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  PSecBufferDesc   pInput,
  unsigned long    fContextReq,
  unsigned long    TargetDataRep,
  PCtxtHandle      phNewContext,
  PSecBufferDesc   pOutput,
  unsigned long    *pfContextAttr,
  PTimeStamp       ptsExpiry
);

Parameters

AsyncContext

The async call context.

phCredential

A handle to the server credentials. To retrieve this handle, the server calls the SspiAcquireCredentialsHandleAsync function with either the SECPKG_CRED_INBOUND or SECPKG_CRED_BOTH flag set.

phContext

A pointer to a CtxtHandle structure. On the first call to SspiAcceptSecurityContextAsync, this pointer is NULL. On subsequent calls, phContext specifies the partially formed context returned in the phNewContext parameter by the first call.

pInput

A pointer to a SecBufferDesc structure generated by a client call to SspiInitializeSecurityContextAsync. The structure contains the input buffer descriptor.

The first buffer must be of type SECBUFFER_TOKEN and contain the security token received from the client. The second buffer should be of type SECBUFFER_EMPTY.

fContextReq

Bit flags that specify the attributes required by the server to establish the context.

See AcceptSecurityContext: fContextReq for a full list of parameter values.

TargetDataRep

The data representation, such as byte ordering, on the target. This parameter can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.

phNewContext

A pointer to a CtxtHandle structure. On the first call to SspiAcceptSecurityContextAsync, this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter.

pOutput

A pointer to a SecBufferDesc structure that contains the output buffer descriptor. This buffer is sent to the client for input into additional calls to SspiInitializeSecurityContextAsync. An output buffer may be generated even if the function returns SEC_E_OK. Any buffer generated must be sent back to the client application.

On output, this buffer receives a token for the async security context. The token must be sent to the client. The function can also return a buffer of type SECBUFFER_EXTRA.

pfContextAttr

A pointer to a set of bit flags that indicate the attributes of the established context.

See AcceptSecurityContext: pfContextAttr for descriptions of the attributes.

ptsExpiry

A pointer to a TimeStamp structure that receives the expiration time of the context.

See AcceptSecurityContext: ptsExpiry.

Return value

Returns SEC_E_OK if the async request to establish a security context 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 security context received from the client was accepted, SspiGetAsyncCallStatus returns SEC_E_OK or one of the SSPI codes in the table below. 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 second table below.

Return code	Description
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	The function succeeded. The data in the input buffer is incomplete. The application must read additional data from the client and call SspiAcceptSecurityContextAsync again.
SEC_I_COMPLETE_AND_CONTINUE 0x00090314L	The function succeeded. The server must call CompleteAuthToken and pass the output token to the client. The server must then wait for a return token from the client before making another call to SspiAcceptSecurityContextAsync.
SEC_I_COMPLETE_NEEDED 0x00090313L	The function succeeded. The server must finish building the message from the client before calling CompleteAuthToken.
SEC_I_CONTINUE_NEEDED 0x00090312L	The function succeeded. The server must send the output token to the client and wait for a returned token. The returned token should be passed in pInput for another call to SspiAcceptSecurityContextAsync.

Fatal error codes

Return code	Description
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	The function failed. There is not enough memory available to complete the requested action.
SEC_E_INTERNAL_ERROR 0x80090304L	The function failed. An error occurred that did not map to an SSPI error code.
SEC_E_INVALID_HANDLE 0x80100003L	The function failed. The handle passed to the function is not valid.
SEC_E_INVALID_TOKEN 0x80090308L	The function failed. The token passed to the function is not valid.
SEC_E_LOGON_DENIED 0x8009030CL	The logon failed.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	The function failed. No authority could be contacted for authentication. This could be due to the following conditions: The domain name of the authenticating party is incorrect. The domain is unavailable. The trust relationship has failed.
SEC_E_NO_CREDENTIALS 0x8009030EL	The function failed. The credentials handle specified in the phCredential parameter is not valid.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	The function failed. The fContextReq parameter specified a context attribute flag (ASC_REQ_DELEGATE or ASC_REQ_PROMPT_FOR_CREDS) that was not valid.

Remarks

The SspiAcceptSecurityContextAsync function is the server counterpart to the SspiInitializeSecurityContextAsync function.

The caller is responsible for determining whether the final context attributes are sufficient. For example, if confidentiality (encryption) was requested but could not be established, some applications may choose to shut down the connection immediately. If the security context cannot be established, the server must free the partially created context by calling the SspiDeleteSecurityContextAsync function.

See AcceptSecurityContext for additional remarks.

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