EpcAuthContext

## 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);

## Object Hierarchy

      GFlags
       +----EpcAuthFlags

## 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

    1
    2
    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

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    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 {
      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