InfSaslContext

InfSaslContext — Asynchronous SASL processing

Stability Level

Unstable, unless otherwise indicated

Synopsis

#include <libinfinity/common/inf-sasl-context.h>

                    InfSaslContext;
                    InfSaslContextSession;
void                (*InfSaslContextCallbackFunc)       (InfSaslContextSession *session,
                                                         Gsasl_property property,
                                                         gpointer session_data,
                                                         gpointer user_data);
void                (*InfSaslContextSessionFeedFunc)    (InfSaslContextSession *session,
                                                         const char *data,
                                                         gboolean needs_more,
                                                         const GError *error,
                                                         gpointer user_data);
InfSaslContext *    inf_sasl_context_new                (GError **error);
InfSaslContext *    inf_sasl_context_ref                (InfSaslContext *context);
void                inf_sasl_context_unref              (InfSaslContext *context);
void                inf_sasl_context_set_callback       (InfSaslContext *context,
                                                         InfSaslContextCallbackFunc callback,
                                                         gpointer user_data);
InfSaslContextSession * inf_sasl_context_client_start_session
                                                        (InfSaslContext *context,
                                                         InfIo *io,
                                                         const char *mech,
                                                         gpointer session_data,
                                                         GError **error);
char *              inf_sasl_context_client_list_mechanisms
                                                        (InfSaslContext *context,
                                                         GError **error);
gboolean            inf_sasl_context_client_supports_mechanism
                                                        (InfSaslContext *context,
                                                         const char *mech);
const char *        inf_sasl_context_client_suggest_mechanism
                                                        (InfSaslContext *context,
                                                         const char *mechanisms);
InfSaslContextSession * inf_sasl_context_server_start_session
                                                        (InfSaslContext *context,
                                                         InfIo *io,
                                                         const char *mech,
                                                         gpointer session_data,
                                                         GError **error);
char *              inf_sasl_context_server_list_mechanisms
                                                        (InfSaslContext *context,
                                                         GError **error);
gboolean            inf_sasl_context_server_supports_mechanism
                                                        (InfSaslContext *context,
                                                         const char *mech);
void                inf_sasl_context_stop_session       (InfSaslContext *context,
                                                         InfSaslContextSession *session);
const char *        inf_sasl_context_session_get_property
                                                        (InfSaslContextSession *session,
                                                         Gsasl_property prop);
void                inf_sasl_context_session_set_property
                                                        (InfSaslContextSession *session,
                                                         Gsasl_property prop,
                                                         const char *value);
void                inf_sasl_context_session_continue   (InfSaslContextSession *session,
                                                         int retval);
void                inf_sasl_context_session_feed       (InfSaslContextSession *session,
                                                         const char *data,
                                                         InfSaslContextSessionFeedFunc func,
                                                         gpointer user_data);
gboolean            inf_sasl_context_session_is_processing
                                                        (InfSaslContextSession *session);

Object Hierarchy

  GBoxed
   +----InfSaslContext

Description

InfSaslContext is a wrapper for the Gsasl library. It basically adds functionality to provide properties asynchronously to Gsasl, so that for example a dialog can be shown to the user before continuing with the authentication process. With Gsasl, it is expected that the callback function sets the requested property before returning, which makes it hard to give control back to a main loop while waiting for user input.

This wrapper makes sure the callback is called in another thread so that it can block without affecting the rest of the program. Use inf_sasl_context_session_feed() as a replacement for gsasl_step64(). Instead of returning the result data directly, the function calls a callback once all properties requested have been provided.

All threading internals are hidden by the wrapper, so all callbacks are issued in the user thread. However, it requires an InfIo object to dispatch messages to it. Also, all InfSaslContext functions are fully thread-safe.

Details

InfSaslContext

typedef struct _InfSaslContext InfSaslContext;

InfSaslContext is an opaque data type. You should only access it via the public API functions.


InfSaslContextSession

typedef struct _InfSaslContextSession InfSaslContextSession;

InfSaslContextSession represents an ongoing authentication session. Create with inf_sasl_context_server_start_session() or inf_sasl_context_client_start_session().


InfSaslContextCallbackFunc ()

void                (*InfSaslContextCallbackFunc)       (InfSaslContextSession *session,
                                                         Gsasl_property property,
                                                         gpointer session_data,
                                                         gpointer user_data);

This callback is called whenever a property is required to proceed with authentication. For example, when a password is required, the callback is called with property set to GSASL_PASSCODE.

The function is then expected to set that property using inf_sasl_context_session_set_property() and, once it is done, call inf_sasl_context_session_continue(). This can happen fully asynchronously, that is it does not need to take place directly within the callback but the callback can, for example, open a dialog for the user to enter a password and then once the user closes the dialog call the two functions mentioned above.

session :

A InfSaslContextSession.

property :

The property requested.

session_data :

The session data for session specified in inf_sasl_context_server_start_session() or inf_sasl_context_client_start_session().

user_data :

The user data specified in inf_sasl_context_set_callback().

InfSaslContextSessionFeedFunc ()

void                (*InfSaslContextSessionFeedFunc)    (InfSaslContextSession *session,
                                                         const char *data,
                                                         gboolean needs_more,
                                                         const GError *error,
                                                         gpointer user_data);

This function is called in response to inf_sasl_context_session_feed(). When all required properties (if any) have been provided by the callback function then this function is called with the response to send to the remote site.

If an error occurred then error will be set and data will be NULL.

session :

A InfSaslContextSession.

data :

The response to the fed data, base64 encoded and null-terminated.

needs_more :

If TRUE then inf_sasl_context_session_feed() needs to be called again with more data, otherwise the authentication has finished.

error :

This is nonzero if an error occured while processing the input data.

user_data :

The user data specified in inf_sasl_context_session_feed().

inf_sasl_context_new ()

InfSaslContext *    inf_sasl_context_new                (GError **error);

Creates a new InfSaslContext with a reference count of 1. If the function fails it returns NULL and error is set.

error :

Location to store error information, if any.

Returns :

A new InfSaslContext, or NULL on error. Free with inf_sasl_context_unref() when no longer needed.

inf_sasl_context_ref ()

InfSaslContext *    inf_sasl_context_ref                (InfSaslContext *context);

Increases the reference count of context by one.

context :

A InfSaslContext.

Returns :

The passed in pointer, context.

inf_sasl_context_unref ()

void                inf_sasl_context_unref              (InfSaslContext *context);

Decreases the reference count of sasl by one. When the reference count reaches zero then the object is freed and may no longer be used. If that happens then also all sessions created with inf_sasl_context_client_start_session() or inf_sasl_context_server_start_session() are stopped automatically.

context :

A InfSaslContext.

inf_sasl_context_set_callback ()

void                inf_sasl_context_set_callback       (InfSaslContext *context,
                                                         InfSaslContextCallbackFunc callback,
                                                         gpointer user_data);

Sets the callback to call when, during authentication, a certain properties needs to be provided, such as a username or a password. The callback function is expected to set the requested property using inf_sasl_context_session_set_property() and then call inf_sasl_context_session_continue() with retval being GSASL_OK. If it cannot provide the property then it should only call inf_sasl_context_session_continue() with retval indicating the problem.

The callback function does not need to provide the property immediately. It is also allowed return and call inf_sasl_context_session_continue() later.

context :

A InfSaslContext.

callback :

A function to call to query properties for authentication.

user_data :

Additional context to pass to callback.

inf_sasl_context_client_start_session ()

InfSaslContextSession * inf_sasl_context_client_start_session
                                                        (InfSaslContext *context,
                                                         InfIo *io,
                                                         const char *mech,
                                                         gpointer session_data,
                                                         GError **error);

Starts a new client-side SASL session using mech for authentication. When the session finished, that is either when an error occurred or the authentication finished successfully, use inf_sasl_context_stop_session().

The callback function will be called in the thread that io runs in.

context :

A InfSaslContext.

io :

The InfIo main loop to which to dispatch callbacks.

mech :

The mechanism to use for the session.

session_data :

Session-specific data to provide to the InfSaslContextCallbackFunc.

error :

Location to store error information, if any.

Returns :

A InfSaslContextSession.

inf_sasl_context_client_list_mechanisms ()

char *              inf_sasl_context_client_list_mechanisms
                                                        (InfSaslContext *context,
                                                         GError **error);

Returns a newly allocated space-separated string containing SASL mechanisms that context supports for client sessions.

context :

A InfSaslContext.

error :

Location to store error information, if any.

Returns :

A newly allocated string. Free with gsasl_free() when no longer in use.

inf_sasl_context_client_supports_mechanism ()

gboolean            inf_sasl_context_client_supports_mechanism
                                                        (InfSaslContext *context,
                                                         const char *mech);

Checks whether context supports the mechanism with name mech for client sessions.

context :

A InfSaslContext.

mech :

The name of the mechanism to be tested.

Returns :

TRUE if mech is supported or FALSE otherwise.

inf_sasl_context_client_suggest_mechanism ()

const char *        inf_sasl_context_client_suggest_mechanism
                                                        (InfSaslContext *context,
                                                         const char *mechanisms);

Given a list of SASL mechanisms this function suggests the which is the "best" one to be used.

context :

A InfSaslContext.

mechanisms :

Space-separated list of SASL mechanism names.

Returns :

The name of the suggested mechanism.

inf_sasl_context_server_start_session ()

InfSaslContextSession * inf_sasl_context_server_start_session
                                                        (InfSaslContext *context,
                                                         InfIo *io,
                                                         const char *mech,
                                                         gpointer session_data,
                                                         GError **error);

Starts a new server-side SASL session using mech for authentication. When the session finished, that is either when an error occurred or the authentication finished successfully, use inf_sasl_context_stop_session().

The callback function will be called in the thread that io runs in.

context :

A InfSaslContext.

io :

The InfIo main loop to which to dispatch callbacks.

mech :

The mechanism to use for the session.

session_data :

Session-specific data to provide to the InfSaslContextCallbackFunc.

error :

Location to store error information, if any.

Returns :

A InfSaslContextSession.

inf_sasl_context_server_list_mechanisms ()

char *              inf_sasl_context_server_list_mechanisms
                                                        (InfSaslContext *context,
                                                         GError **error);

Returns a newly allocated space-separated string containing SASL mechanisms that context supports for server sessions.

context :

A InfSaslContext.

error :

Location to store error information, if any.

Returns :

A newly allocated string. Free with gsasl_free() when no longer in use.

inf_sasl_context_server_supports_mechanism ()

gboolean            inf_sasl_context_server_supports_mechanism
                                                        (InfSaslContext *context,
                                                         const char *mech);

Checks whether context supports the mechanism with name mech for server sessions.

context :

A InfSaslContext.

mech :

The name of the mechanism to be tested.

Returns :

TRUE if mech is supported or FALSE otherwise.

inf_sasl_context_stop_session ()

void                inf_sasl_context_stop_session       (InfSaslContext *context,
                                                         InfSaslContextSession *session);

Finishes session and frees all resources allocated to it. This can be used to cancel an authentication session, or to free it after it finished (either successfully or not).

session should no longer be used after this function was called.

context :

A InfSaslContext.

session :

A InfSaslContextSession created with context.

inf_sasl_context_session_get_property ()

const char *        inf_sasl_context_session_get_property
                                                        (InfSaslContextSession *session,
                                                         Gsasl_property prop);

Returns the value of the property prop in session. If the value does not yet exist then this function returns NULL. It does not invoke the InfSaslContextCallbackFunc to query it.

session :

A InfSaslContextSession.

prop :

A SASL property.

Returns :

The value of the property, or NULL. The value is owned by the session and must not be freed.

inf_sasl_context_session_set_property ()

void                inf_sasl_context_session_set_property
                                                        (InfSaslContextSession *session,
                                                         Gsasl_property prop,
                                                         const char *value);

Sets the property prop in session to value.

session :

A InfSaslContextSession.

prop :

A SASL property.

value :

The value to set the property to.

inf_sasl_context_session_continue ()

void                inf_sasl_context_session_continue   (InfSaslContextSession *session,
                                                         int retval);

When the callback function specified in inf_sasl_context_set_callback() is called then session waits for the user to call inf_sasl_context_session_continue(). It should do so once it provided the requested property using inf_sasl_context_session_set_property() with retval being GSASL_OK. If it decides that the property cannot be provided then it should still call this function with retval being a SASL error code specifying the problem.

session :

A InfSaslContextSession.

retval :

Error code of the operation requested.

inf_sasl_context_session_feed ()

void                inf_sasl_context_session_feed       (InfSaslContextSession *session,
                                                         const char *data,
                                                         InfSaslContextSessionFeedFunc func,
                                                         gpointer user_data);

This function feeds data from the session's remote counterpart to session. It should be base64 encoded. This function will, asynchronously, process the data and query for properties it requires to do so. Once it has finished, func is called with output data to send to the remote side to be fed to its session counterpart.

This function must not be called again before func was called.

session :

A InfSaslContextSession.

data :

The data to feed to the SASL session.

func :

The function to call when the data has been processed.

user_data :

Additional user data to pass to func.

inf_sasl_context_session_is_processing ()

gboolean            inf_sasl_context_session_is_processing
                                                        (InfSaslContextSession *session);

Returns whether the session is currently asynchronously processing data fed to it with inf_sasl_context_session_feed(). In this case the first call needs to finish before another one is allowed to be made.

session :

A InfSaslContextSession.

Returns :

Whether session is currently processing data asynchronously.