![]() |
![]() |
![]() |
libinfinity-0.5 Reference Manual | ![]() |
---|---|---|---|---|
Top | Description | Object Hierarchy |
#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
);
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.
typedef struct _InfSaslContext InfSaslContext;
InfSaslContext is an opaque data type. You should only access it via the public API functions.
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()
.
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.
|
A InfSaslContextSession. |
|
The property requested. |
|
The session data for session specified in
inf_sasl_context_server_start_session() or
inf_sasl_context_client_start_session() . |
|
The user data specified in inf_sasl_context_set_callback() . |
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
.
|
A InfSaslContextSession. |
|
The response to the fed data, base64 encoded and null-terminated. |
|
If TRUE then inf_sasl_context_session_feed() needs to be
called again with more data, otherwise the authentication has finished. |
|
This is nonzero if an error occured while processing the input data. |
|
The user data specified in inf_sasl_context_session_feed() . |
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.
|
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. |
InfSaslContext * inf_sasl_context_ref (InfSaslContext *context
);
Increases the reference count of context
by one.
|
A InfSaslContext. |
Returns : |
The passed in pointer, context . |
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.
|
A InfSaslContext. |
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.
|
A InfSaslContext. |
|
A function to call to query properties for authentication. |
|
Additional context to pass to callback . |
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.
|
A InfSaslContext. |
|
The InfIo main loop to which to dispatch callbacks. |
|
The mechanism to use for the session. |
|
Session-specific data to provide to the InfSaslContextCallbackFunc. |
|
Location to store error information, if any. |
Returns : |
A InfSaslContextSession. |
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.
|
A InfSaslContext. |
|
Location to store error information, if any. |
Returns : |
A newly allocated string. Free with gsasl_free() when no longer
in use. |
gboolean inf_sasl_context_client_supports_mechanism (InfSaslContext *context
,const char *mech
);
Checks whether context
supports the mechanism with name mech
for
client sessions.
|
A InfSaslContext. |
|
The name of the mechanism to be tested. |
Returns : |
TRUE if mech is supported or FALSE otherwise. |
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.
|
A InfSaslContext. |
|
Space-separated list of SASL mechanism names. |
Returns : |
The name of the suggested mechanism. |
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.
|
A InfSaslContext. |
|
The InfIo main loop to which to dispatch callbacks. |
|
The mechanism to use for the session. |
|
Session-specific data to provide to the InfSaslContextCallbackFunc. |
|
Location to store error information, if any. |
Returns : |
A InfSaslContextSession. |
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.
|
A InfSaslContext. |
|
Location to store error information, if any. |
Returns : |
A newly allocated string. Free with gsasl_free() when no longer
in use. |
gboolean inf_sasl_context_server_supports_mechanism (InfSaslContext *context
,const char *mech
);
Checks whether context
supports the mechanism with name mech
for
server sessions.
|
A InfSaslContext. |
|
The name of the mechanism to be tested. |
Returns : |
TRUE if mech is supported or FALSE otherwise. |
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.
|
A InfSaslContext. |
|
A InfSaslContextSession created with context . |
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.
|
A InfSaslContextSession. |
|
A SASL property. |
Returns : |
The value of the property, or NULL . The value is owned by the
session and must not be freed. |
void inf_sasl_context_session_set_property (InfSaslContextSession *session
,Gsasl_property prop
,const char *value
);
Sets the property prop
in session
to value
.
|
A InfSaslContextSession. |
|
A SASL property. |
|
The value to set the property to. |
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.
|
A InfSaslContextSession. |
|
Error code of the operation requested. |
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.
|
A InfSaslContextSession. |
|
The data to feed to the SASL session. |
|
The function to call when the data has been processed. |
|
Additional user data to pass to func . |