SaslAcceptSecurityContext function (sspi.h)

Article
12/09/2022

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, optional]  PCtxtHandle    phContext,
  [in]            PSecBufferDesc pInput,
  [in]            unsigned long  fContextReq,
  [in]            unsigned long  TargetDataRep,
  [out]           PCtxtHandle    phNewContext,
  [in, out]       PSecBufferDesc pOutput,
  [out]           unsigned long  *pfContextAttr,
  [out, optional] PTimeStamp     ptsExpiry
);

Parameters

[in] phCredential

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

[in, optional] phContext

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.

[in] pInput

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.

[in] fContextReq

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.

[in] TargetDataRep

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

[out] phNewContext

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.

[in, out] pOutput

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.

[out] pfContextAttr

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.

[out, optional] ptsExpiry

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.

Return code	Description
SEC_E_ALGORITHM_MISMATCH	Authz processing is not permitted.
SEC_E_INSUFFICIENT_MEMORY	Not enough memory is available to complete the request.
SEC_E_INVALID_TOKEN	No Token buffer is located in the pOutput parameter, or the message failed to decrypt.

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

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	sspi.h (include Security.h)
Library	Secur32.lib
DLL	Secur32.dll