SaslAcceptSecurityContext function

The SaslAcceptSecurityContext function wraps a standard call to the Security Support Provider Interface AcceptSecurityContext (General) function and includes creation of SASL server cookies.

Syntax

SECURITY_STATUS SEC_ENTRY SaslAcceptSecurityContext(
  _In_      PCredHandle           phCredential,
  _In_opt_  PCtxtHandle           phContext,
  _In_      PSecBufferDesc        pInput,
  _In_      unsigned long         fContextReq,
  _In_      unsigned long         TargetDataRep,
  _Out_     PCtxtHandle           phNewContext,
  _Inout_   PSecBufferDesc        pOutput,
  _Out_     unsigned long SEC_FAR *pfContextAttr,
  _Out_opt_ PTimeStamp            ptsExpiry
);

Parameters

phCredential [in]

A handle to the server's credentials. The server calls the AcquireCredentialsHandle function with the INBOUND flag set to retrieve this handle.

phContext [in, optional]

Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (General), this pointer is NULL. On subsequent calls, phContext is the handle to the partially formed context that was returned in the phNewContext parameter by the first call.

pInput [in]

Pointer to a SecBufferDesc structure generated by a client call to the InitializeSecurityContext (General) function that contains the input buffer descriptor.

SASL requires a single buffer of type SECBUFFER_TOKEN. The buffer is empty for the first call to the AcceptSecurityContext (General) function and contains the challenge response received from the client for the second call.

fContextReq [in]

Bit flags that specify the attributes required by the server to establish the context. Bit flags can be combined using bitwise-OR operations. The following table shows the possible values.

Value	Meaning
ASC_REQ_CONFIDENTIALITY	Encrypt and decrypt messages. Valid with the Digest SSP for SASL only.
ASC_REQ_HTTP	Use Digest for HTTP. Omit this flag to use Digest as an SASL mechanism.

 

TargetDataRep [in]

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

phNewContext [out]

Pointer to a CtxtHandle structure. On the first call to AcceptSecurityContext (General), this pointer receives the new context handle. On subsequent calls, phNewContext can be the same as the handle specified in the phContext parameter.

pOutput [in, out]

Pointer to a SecBufferDesc structure that contains the output buffer descriptor. This buffer is sent to the client for input into additional calls to InitializeSecurityContext (General). 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.

pfContextAttr [out]

Pointer to a variable that receives a set of bit flags indicating the attributes of the established context. For a description of the various attributes, see Context Requirements. Flags used for this parameter are prefixed with ASC_RET, such as ASC_RET_DELEGATE.

Do not check for security-related attributes until the final function call returns successfully. Attribute flags not related to security, such as the ASC_RET_ALLOCATED_MEMORY flag, can be checked before the final return.

ptsExpiry [out, optional]

Pointer to a TimeStamp structure that receives the expiration time of the context. It is recommended that the security package always return this value in local time.

Note  Until the last call of the authentication process, the expiration time for the context can be incorrect because more information will be provided during later stages of the negotiation. Therefore, ptsTimeStamp must be NULL until the last call to the function.

 

Return value

If the call is completed successfully, this function returns SEC_E_OK. The following table shows some possible failure return values.

Remarks

The final call of the AcceptSecurityContext (General) function that returns SEC_E_OK is identified. If a return token is produced, SASL processing is suspended for one round trip back to the client to allow the final token to be processed. After the exchange is completed, SEC_E_CONTINUE_NEEDED is returned to the application with an additional SASL server cookie encrypted with SSPI message functions. The initial server cookie indicates if INTEGRITY and PRIVACY are supported. This initial server cookie is processed by the client, and the client returns a client cookie to indicate which services the client requests. The client cookie is then decrypted by the server and the final services are determined for the following message traffic.

Requirements