---

9 Session Functions

gsasl_client_start

Function: int gsasl_client_start (Gsasl * ctx, const char * mech, Gsasl_session ** sctx) ¶

ctx: libgsasl handle.

mech: name of SASL mechanism.

sctx: pointer to client handle.

This functions initiates a client SASL authentication. This function must be called before any other gsasl_client_*() function is called.

Return value: Returns GSASL_OK if successful, or error code.

gsasl_server_start

Function: int gsasl_server_start (Gsasl * ctx, const char * mech, Gsasl_session ** sctx) ¶

ctx: libgsasl handle.

mech: name of SASL mechanism.

sctx: pointer to server handle.

This functions initiates a server SASL authentication. This function must be called before any other gsasl_server_*() function is called.

Return value: Returns GSASL_OK if successful, or error code.

gsasl_step

Function: int gsasl_step (Gsasl_session * sctx, const char * input, size_t input_len, char ** output, size_t * output_len) ¶

sctx: libgsasl session handle.

input: input byte array.

input_len: size of input byte array.

output: newly allocated output byte array.

output_len: pointer to output variable with size of output byte array.

Perform one step of SASL authentication. This reads data from the other end (from input and input_len ), processes it (potentially invoking callbacks to the application), and writes data to server (into newly allocated variable output and output_len that indicate the length of output ).

The contents of the output buffer is unspecified if this functions returns anything other than GSASL_OK or GSASL_NEEDS_MORE . If this function return GSASL_OK or GSASL_NEEDS_MORE , however, the output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling gsasl_free( output ).

Return value: Returns GSASL_OK if authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.

gsasl_step64

Function: int gsasl_step64 (Gsasl_session * sctx, const char * b64input, char ** b64output) ¶

sctx: libgsasl client handle.

b64input: input base64 encoded byte array.

b64output: newly allocated output base64 encoded byte array.

This is a simple wrapper around gsasl_step() that base64 decodes the input and base64 encodes the output.

The contents of the b64output buffer is unspecified if this functions returns anything other than GSASL_OK or GSASL_NEEDS_MORE . If this function return GSASL_OK or GSASL_NEEDS_MORE , however, the b64output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling gsasl_free( b64output ).

Return value: Returns GSASL_OK if authenticated terminated successfully, GSASL_NEEDS_MORE if more data is needed, or error code.

gsasl_finish

Function: void gsasl_finish (Gsasl_session * sctx) ¶

sctx: libgsasl session handle.

Destroy a libgsasl client or server handle. The handle must not be used with other libgsasl functions after this call.

gsasl_encode

Function: int gsasl_encode (Gsasl_session * sctx, const char * input, size_t input_len, char ** output, size_t * output_len) ¶

sctx: libgsasl session handle.

input: input byte array.

input_len: size of input byte array.

output: newly allocated output byte array.

output_len: pointer to output variable with size of output byte array.

Encode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.

The output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling gsasl_free( output ).

Return value: Returns GSASL_OK if encoding was successful, otherwise an error code.

gsasl_decode

Function: int gsasl_decode (Gsasl_session * sctx, const char * input, size_t input_len, char ** output, size_t * output_len) ¶

sctx: libgsasl session handle.

input: input byte array.

input_len: size of input byte array.

output: newly allocated output byte array.

output_len: pointer to output variable with size of output byte array.

Decode data according to negotiated SASL mechanism. This might mean that data is integrity or privacy protected.

The output buffer is allocated by this function, and it is the responsibility of caller to deallocate it by calling gsasl_free( output ).

Return value: Returns GSASL_OK if encoding was successful, otherwise an error code.

gsasl_mechanism_name

Function: const char * gsasl_mechanism_name (Gsasl_session * sctx) ¶

sctx: libgsasl session handle.

This function returns the name of the SASL mechanism used in the session. The pointer must not be deallocated by the caller.

Return value: Returns a zero terminated character array with the name of the SASL mechanism, or NULL if not known.

Since: 0.2.28