SspiInitializeSecurityContextAsyncA function (sspi.h)

Article
07/27/2022

The SspiInitializeSecurityContextAsyncA function initiates the client side, outbound security context from a credential handle. The function is used to build a security context between the client application and a remote peer. SspiInitializeSecurityContextAsyncA returns a token that the client must pass to the remote peer, which the peer in turn submits to the local security implementation through the SspiAcceptSecurityContextAsync call.

Note

This function serves as the asynchronous counterpart to theInitializeSecurityContext function.

Syntax

SECURITY_STATUS SspiInitializeSecurityContextAsyncA(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  LPSTR            pszTargetName,
  unsigned long    fContextReq,
  unsigned long    Reserved1,
  unsigned long    TargetDataRep,
  PSecBufferDesc   pInput,
  unsigned long    Reserved2,
  PCtxtHandle      phNewContext,
  PSecBufferDesc   pOutput,
  unsigned long    *pfContextAttr,
  PTimeStamp       ptsExpiry
);

Parameters

AsyncContext

The async call context.

phCredential

A handle to the credentials returned by AcquireCredentialsHandle. This handle is used to build the security context.

phContext

A pointer to an existing CtxtHandle structure.

pszTargetName

A pointer to a null-terminated string that indicates the target of the context. The string contents are security package specific, as described in the following table. This list is not exhaustive. Additional system SSPs and third party SSPs can be added to a system.

SSP in use	Meaning
Digest	Null-terminated string that uniquely identifies the URI of the requested resource. The string must be composed of characters that are allowed in a URI and must be representable by the US ASCII code set. Percent encoding can be used to represent characters outside the US ASCII code set.
Kerberos or Negotiate	Service principal name (SPN) or the security context of the destination server.
NTLM	Service principal name (SPN) or the security context of the destination server.
Schannel/SSL	Null-terminated string that uniquely identifies the target server. Schannel uses this value to verify the server certificate. Schannel also uses this value to locate the session in the session cache when reestablishing a connection. The cached session is used only if all of the following conditions are met: The target name is the same. The cache entry has not expired. The application process that calls the function is the same. The logon session is the same. The credential handle is the same.

fContextReq

Bit flags that indicate requests for the context.

See InitializeSecurityContext: fContextReq for a list of flag values and their meanings.

Reserved1

This parameter is reserved and must be set to zero.

TargetDataRep

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

pInput

A pointer to a SecBufferDesc structure that contains pointers to the buffers supplied as input to the package.

Reserved2

This parameter is reserved and must be set to zero.

phNewContext

A pointer to a CtxtHandle structure.

pOutput

A pointer to a SecBufferDesc structure that contains pointers to the SecBuffer structure that receives the output data.

pfContextAttr

A pointer to a variable to receive a set of bit flags that indicate the attributes of the established context. For a description of the various attributes, see Context Requirements.

ptsExpiry

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

Return value

Returns SEC_E_OK if the async request to establish a security context was successfully queued for execution, otherwise, returns the error generated attempting to queue it. To retrieve the status of the operation, use SspiGetAsyncCallStatus.

If the security context received from the server 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_I_COMPLETE_AND_CONTINUE 0x00090314L	The client must call CompleteAuthToken and pass the output token to the server. The client then waits for a returned token and passes it, in another call, to SspiInitializeSecurityContextAsyncA.
SEC_I_COMPLETE_NEEDED 0x00090313L	The client must finish building the message from the server before calling CompleteAuthToken.
SEC_I_CONTINUE_NEEDED 0x00090312L	The client must send the output token to the server and wait for a return token. The returned token is then passed in another call to SspiInitializeSecurityContextAsyncA. The output token can be empty.
SEC_I_INCOMPLETE_CREDENTIALS	Use with Schannel. The server has requested client authentication, and the supplied credentials either do not include a certificate or the certificate was not issued by a certification authority that is trusted by the server.
SEC_E_INCOMPLETE_MESSAGE 0x80090318L	Data for the whole message was not read from the wire. When this value is returned, the pInput buffer contains a SecBuffer structure with a BufferType member of SECBUFFER_MISSING. The cbBuffer member of SecBuffer contains a value that indicates the number of additional bytes that the function must read from the client before this function succeeds. While this number is not always accurate, using it can help improve performance by avoiding multiple calls to this function.
SEC_E_OK 0x00000000L	The security context received from the client was accepted. If the function generated an output token, the token must be sent to the server.

Fatal error codes

Return code	Description
SEC_E_INSUFFICIENT_MEMORY 0x80090300L	There is not enough memory available to complete the requested action.
SEC_E_INTERNAL_ERROR 0x80090304L	An error occurred that did not map to an SSPI error code.
SEC_E_INVALID_HANDLE 0x80100003L	The handle passed to the function is not valid.
SEC_E_INVALID_TOKEN 0x80090308L	The error is due to a malformed input token, such as a token corrupted in transit, a token of incorrect size, or a token passed into the wrong security package. Passing a token to the wrong package can happen if the client and server did not negotiate the proper security package.
SEC_E_LOGON_DENIED 0x8009030CL	The logon failed.
SEC_E_NO_AUTHENTICATING_AUTHORITY 0x80090311L	No authority could be contacted for authentication. The domain name of the authenticating party could be wrong, the domain could be unreachable, or there might have been a trust relationship failure.
SEC_E_NO_CREDENTIALS 0x8009030EL	No credentials are available in the security package.
SEC_E_TARGET_UNKNOWN	The target was not recognized.
SEC_E_UNSUPPORTED_FUNCTION 0x80090302L	A context attribute flag that is not valid (ISC_REQ_DELEGATE or ISC_REQ_PROMPT_FOR_CREDS) was specified in the fContextReq parameter.
SEC_E_WRONG_PRINCIPAL	The principal that received the authentication request is not the same as the one passed into the pszTargetName parameter. This indicates a failure in mutual authentication.

Remarks

See InitializeSecurityContext for complete 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