EpcAuthContext

EpcAuthContext — manage authentication

Stability Level

Unstable, unless otherwise indicated

Synopsis


#include <libepc/publish.h>

enum                EpcAuthFlags;
gboolean            (*EpcAuthHandler)                   (EpcAuthContext *context,
                                                         const gchar *username,
                                                         gpointer user_data);
                    EpcAuthContext;
gboolean            epc_auth_context_check_password     (const EpcAuthContext *context,
                                                         const gchar *password);
const gchar*        epc_auth_context_get_key            (const EpcAuthContext *context);
const gchar*        epc_auth_context_get_password       (const EpcAuthContext *context);
EpcPublisher*       epc_auth_context_get_publisher      (const EpcAuthContext *context);

GFlagsClass*        epc_auth_flags_get_class            (void);
const gchar*        epc_auth_flags_to_string            (EpcAuthFlags value);

Description

With each request the EpcPublisher verifies access authorization by calling the EpcAuthHandler registered for the key in question, if any. Information about that process is stored in the EpcAuthContext structure.

To register an authentication handler call epc_publisher_set_auth_handler():

Example 3. Register an authentication handler

  epc_publisher_set_auth_handler (publisher, "sensitive-key",
                                  my_auth_handler, my_object);
 


To verify that the user password provided password matches the expected one use epc_auth_context_check_password():

Example 4. Verify a password

  static gboolean
  my_auth_handler (EpcAuthContext *context,
                   const gchar    *username,
                   gpointer        user_data)
  {
    MyObject *self = user_data;
    const gchar *expected_password;
    const gchar *requested_key;

    requested_key = epc_auth_context_get_key (context);
    expected_password = lookup_password (self, requested_key);

    return epc_auth_context_check_password (context, expected_password);
  }
 


Details

enum EpcAuthFlags

typedef enum /* <flags> */
{
  EPC_AUTH_DEFAULT =                     0,
  EPC_AUTH_PASSWORD_TEXT_NEEDED =       (1 << 0)
} EpcAuthFlags;

These flags specify the authentication behaviour of an EpcPublisher.

EPC_AUTH_DEFAULT

The default authentication settings.

EPC_AUTH_PASSWORD_TEXT_NEEDED

Set this flag when your EpcAuthFlags needs the supplied password in plain text - for instance to pass it to a database server used by your application. This flag replaces the secure Digest authentication scheme with the insecure Basic authentication scheme. Therefore this setting is valid only when the publisher's transport protocol is EPC_PROTOCOL_HTTPS (secure http).

EpcAuthHandler ()

gboolean            (*EpcAuthHandler)                   (EpcAuthContext *context,
                                                         const gchar *username,
                                                         gpointer user_data);

Functions implementing this callback shall return TRUE when the credentials provided by the authentication request grant access to the resource described by context.

The username is NULL when no creditials were passed, and anonymous access is tried.

See also epc_publisher_set_auth_flags. When EPC_AUTH_DEFAULT is used, you should call epc_auth_context_check_password to verify that the password passed in the request matches the known password for that user. In this case there is no way to retrieve the password from the EpcAuthContext because the network protocol transfers just a hash code, not the actual password.

However, when EPC_AUTH_PASSWORD_TEXT_NEEDED is used, you should call epc_auth_context_get_password() and then do your own authentication check. For instance, you might need to delegate the authentication to some other code or server, such as a database server.

context :

the EpcAuthContext

username :

the username provided for authentication, or NULL

user_data :

user data set when the signal handler was installed

Returns :

TRUE when access is granted, and FALSE otherwise.

EpcAuthContext

typedef struct _EpcAuthContext EpcAuthContext;

This data structure describes a pending authentication request which shall be verified by an EpcAuthHandler installed by epc_publisher_set_auth_handler().

Note

There is no way to retrieve the password from the EpcAuthContext, as the network protocol transfers just a hash code, not the actual password.


epc_auth_context_check_password ()

gboolean            epc_auth_context_check_password     (const EpcAuthContext *context,
                                                         const gchar *password);

Verifies that the password supplied with the network request matches the password the application expects. There is no way to retrieve the password from the EpcAuthContext, as the network protocol transfers just a hash code, not the actual password.

context :

a EpcAuthContext

password :

the expected password

Returns :

TRUE when the sent password matches, or FALSE otherwise.

epc_auth_context_get_key ()

const gchar*        epc_auth_context_get_key            (const EpcAuthContext *context);

Queries the resource key associated with the authentication context.

context :

a EpcAuthContext

Returns :

The resource key.

epc_auth_context_get_password ()

const gchar*        epc_auth_context_get_password       (const EpcAuthContext *context);

Queries the password sent for the authentication context when Basic authentication was allowed for the context, and NULL otherwise.

See also: EPC_AUTH_PASSWORD_TEXT_NEEDED

context :

a EpcAuthContext

Returns :

The password sent, or NULL.

epc_auth_context_get_publisher ()

EpcPublisher*       epc_auth_context_get_publisher      (const EpcAuthContext *context);

Queries the EpcPublisher owning the authentication context.

context :

a EpcAuthContext

Returns :

The owning EpcPublisher.

epc_auth_flags_get_class ()

GFlagsClass*        epc_auth_flags_get_class            (void);

Retrieves the GFlagsClass describing the EpcAuthFlags flags.

Returns :

The GFlagsClass describing EpcAuthFlags.

epc_auth_flags_to_string ()

const gchar*        epc_auth_flags_to_string            (EpcAuthFlags value);

Retrieves the name of a EpcAuthFlags value, or NULL when value is invalid.

value :

a EpcAuthFlags value

Returns :

The string representation of value, or NULL.

See Also

EpcPublisher