EpcAuthContext: Easy Publish and Consume Reference Manual

## EpcAuthContext EpcAuthContext — manage authentication |

## Stability Level

Unstable, unless otherwise indicated

## Functions

gboolean | (*EpcAuthHandler) ()
gboolean | epc_auth_context_check_password ()
const gchar * | epc_auth_context_get_key ()
const gchar * | epc_auth_context_get_password ()
EpcPublisher * | epc_auth_context_get_publisher ()
GFlagsClass * | epc_auth_flags_get_class ()
const gchar * | epc_auth_flags_to_string ()

## Types and Values

enum | EpcAuthFlags
| EpcAuthContext

## Object Hierarchy

        GFlags
        ╰── EpcAuthFlags

## Includes

    #include <libepc/publish.h>

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

## Functions

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

#### Parameters

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.

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

#### Parameters

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` .

#### Parameters

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

#### Parameters

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` .

#### Parameters

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.

#### Parameters

value | a EpcAuthFlags value |

#### Returns

The string representation of `value` , or `NULL`.

## Types and Values

### enum EpcAuthFlags

These flags specify the authentication behaviour of an EpcPublisher.

#### Members

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). |

### 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()`.

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

## See Also

EpcPublisher