Chapter 8. Session Functions

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.

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.

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 free (output).

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

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 free (b64output).

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

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.

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: output byte array.

output_len: size of output byte array.

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

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

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: output byte array.

output_len: size of output byte array.

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

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