SspiInitializeSecurityContextAsyncW function (sspi.h)

The SspiInitializeSecurityContextAsyncW 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. SspiInitializeSecurityContextAsyncW 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 the InitializeSecurityContext function.

Syntax

SECURITY_STATUS SspiInitializeSecurityContextAsyncW(
  SspiAsyncContext *AsyncContext,
  PCredHandle      phCredential,
  PCtxtHandle      phContext,
  PSECURITY_STRING 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

See also

SspiAcceptSecurityContextAsync

SspiAcquireCredentialsHandleAsync