SaslInitializeSecurityContextA function (sspi.h)
The SaslInitializeSecurityContext function wraps a standard call to the Security Support Provider Interface InitializeSecurityContext (General) function and processes SASL server cookies from the server.
Syntax
SECURITY_STATUS SEC_ENTRY SaslInitializeSecurityContextA(
[in] PCredHandle phCredential,
[in] PCtxtHandle phContext,
[in] LPSTR pszTargetName,
[in] unsigned long fContextReq,
[in] unsigned long Reserved1,
[in] unsigned long TargetDataRep,
[in] PSecBufferDesc pInput,
[in] unsigned long Reserved2,
[out] PCtxtHandle phNewContext,
[in, out] PSecBufferDesc pOutput,
[out] unsigned long *pfContextAttr,
[out, optional] PTimeStamp ptsExpiry
);
Parameters
[in] phCredential
A handle to the credentials returned by the
AcquireCredentialsHandle function used to build the security context. Using the SaslInitializeSecurityContext function requires at least OUTBOUND credentials.
[in] phContext
Pointer to a CtxtHandle structure. On the first call to the SaslInitializeSecurityContext function, this pointer is NULL. On the second call, this parameter is a pointer to the handle to the partially formed context returned in the phNewContext parameter by the first call.
[in] pszTargetName
Pointer to a Unicode or ANSI string that indicates the target of the context.
[in] fContextReq
Bit flags that indicate the requirements of the context. Flags used for this parameter are prefixed with ISC_REQ_; for example: ISC_REQ_DELEGATE. Specify combinations of the following attributes flags.
For further descriptions of the various attributes, see Context Requirements.
[in] Reserved1
Reserved value; must be zero.
[in] TargetDataRep
Indicates the data representation, such as byte ordering, on the target. Can be either SECURITY_NATIVE_DREP or SECURITY_NETWORK_DREP.
[in] pInput
Pointer to a SecBufferDesc structure that contains pointers to the buffers supplied as input to the package. The pointer must be NULL on the first call to the function. On subsequent calls to the function, it is a pointer to a buffer allocated with enough memory to hold the token returned by the remote peer.
SASL requires a single buffer of type SECBUFFER_TOKEN that contains the challenge received from the server.
[in] Reserved2
Reserved value; must be zero.
[out] phNewContext
Pointer to a CtxtHandle structure. On the first call to the SaslInitializeSecurityContext function, this pointer receives the new context handle. On the second call, phNewContext can be the same as the handle specified in the phContext parameter.
[in, out] pOutput
Pointer to a SecBufferDesc structure that contains pointers to the SecBuffer structure that receives the output data. If a buffer was typed as SEC_READWRITE in the input, it will be there on output. The system will allocate a buffer for the security token if requested (through ISC_REQ_ALLOCATE_MEMORY) and fill in the address in the buffer descriptor for the security token.
[out] pfContextAttr
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.
Flags used for this parameter are prefixed with ISC_RET_, such as ISC_RET_DELEGATE.
For a list of valid values, see the fContextReq parameter.
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. This parameter is optional and NULL should be passed for short-lived clients.
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 |
---|---|
|
Authz processing is not permitted. |
|
Not enough memory is available to complete the request. |
|
No Token buffer is located in the pOutput parameter, or the message failed to decrypt. |
Remarks
Note
The sspi.h header defines SaslInitializeSecurityContext as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
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 |