SoupAuthDomain

## SoupAuthDomain SoupAuthDomain — Server-side authentication |

## Synopsis

    #include <libsoup/soup.h>

                        SoupAuthDomain;

    void                soup_auth_domain_add_path           (SoupAuthDomain *domain,
                                                             const char *path);
    void                soup_auth_domain_remove_path        (SoupAuthDomain *domain,
                                                             const char *path);
    gboolean            (*SoupAuthDomainFilter)             (SoupAuthDomain *domain,
                                                             SoupMessage *msg,
                                                             gpointer user_data);
    void                soup_auth_domain_set_filter         (SoupAuthDomain *domain,
                                                             SoupAuthDomainFilter filter,
                                                             gpointer filter_data,
                                                             GDestroyNotify dnotify);
    const char *        soup_auth_domain_get_realm          (SoupAuthDomain *domain);

    gboolean            (*SoupAuthDomainGenericAuthCallback)
                                                            (SoupAuthDomain *domain,
                                                             SoupMessage *msg,
                                                             const char *username,
                                                             gpointer user_data);
    void                soup_auth_domain_set_generic_auth_callback
                                                            (SoupAuthDomain *domain,
                                                             SoupAuthDomainGenericAuthCallback auth_callback,
                                                             gpointer auth_data,
                                                             GDestroyNotify dnotify);
    gboolean            soup_auth_domain_check_password     (SoupAuthDomain *domain,
                                                             SoupMessage *msg,
                                                             const char *username,
                                                             const char *password);

    gboolean            soup_auth_domain_covers             (SoupAuthDomain *domain,
                                                             SoupMessage *msg);
    char *              soup_auth_domain_accepts            (SoupAuthDomain *domain,
                                                             SoupMessage *msg);
    void                soup_auth_domain_challenge          (SoupAuthDomain *domain,
                                                             SoupMessage *msg);

    #define             SOUP_AUTH_DOMAIN_REALM
    #define             SOUP_AUTH_DOMAIN_PROXY
    #define             SOUP_AUTH_DOMAIN_ADD_PATH
    #define             SOUP_AUTH_DOMAIN_REMOVE_PATH
    #define             SOUP_AUTH_DOMAIN_FILTER
    #define             SOUP_AUTH_DOMAIN_FILTER_DATA
    #define             SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK
    #define             SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA

## Object Hierarchy

      GObject
       +----SoupAuthDomain
             +----SoupAuthDomainBasic
             +----SoupAuthDomainDigest

## Properties

      "add-path"                 gchar*                : Write
      "filter"                   gpointer              : Read / Write
      "filter-data"              gpointer              : Read / Write
      "generic-auth-callback"    gpointer              : Read / Write
      "generic-auth-data"        gpointer              : Read / Write
      "proxy"                    gboolean              : Read / Write / Construct Only
      "realm"                    gchar*                : Read / Write / Construct Only
      "remove-path"              gchar*                : Write

## Description

A SoupAuthDomain manages authentication for all or part of a SoupServer. To make a server require authentication, first create an appropriate subclass of SoupAuthDomain, and then add it to the server with `soup_server_add_auth_domain()`.

In order for an auth domain to have any effect, you must add one or more paths to it (via `soup_auth_domain_add_path()` or the `SOUP_AUTH_DOMAIN_ADD_PATH` property). To require authentication for all ordinary requests, add the path "/". (Note that this does not include the special "*" URI (eg, "OPTIONS *"), which must be added as a separate path if you want to cover it.)

If you need greater control over which requests should and shouldn't be authenticated, add paths covering everything you might want authenticated, and then use a filter (`soup_auth_domain_set_filter()`) to bypass authentication for those requests that don't need it.

## Details

### SoupAuthDomain

    typedef struct _SoupAuthDomain SoupAuthDomain;

### soup_auth_domain_add_path ()

    void                soup_auth_domain_add_path           (SoupAuthDomain *domain,
                                                             const char *path);

Adds `path` to `domain`, such that requests under `path` on `domain`'s server will require authentication (unless overridden by `soup_auth_domain_remove_path()` or `soup_auth_domain_set_filter()`).

You can also add paths by setting the `SOUP_AUTH_DOMAIN_ADD_PATH` property, which can also be used to add one or more paths at construct time.

`domain` : | a SoupAuthDomain
`path` : | the path to add to `domain`

### soup_auth_domain_remove_path ()

    void                soup_auth_domain_remove_path        (SoupAuthDomain *domain,
                                                             const char *path);

Removes `path` from `domain`, such that requests under `path` on `domain`'s server will NOT require authentication.

This is not simply an undo-er for `soup_auth_domain_add_path()`; it can be used to "carve out" a subtree that does not require authentication inside a hierarchy that does. Note also that unlike with `soup_auth_domain_add_path()`, this cannot be overridden by adding a filter, as filters can only bypass authentication that would otherwise be required, not require it where it would otherwise be unnecessary.

You can also remove paths by setting the `SOUP_AUTH_DOMAIN_REMOVE_PATH` property, which can also be used to remove one or more paths at construct time.

`domain` : | a SoupAuthDomain
`path` : | the path to remove from `domain`

### SoupAuthDomainFilter ()

    gboolean            (*SoupAuthDomainFilter)             (SoupAuthDomain *domain,
                                                             SoupMessage *msg,
                                                             gpointer user_data);

The prototype for a SoupAuthDomain filter; see `soup_auth_domain_set_filter()` for details.

`domain` : | a SoupAuthDomain
`msg` : | a SoupMessage
`user_data` : | the data passed to `soup_auth_domain_set_filter()`
Returns : | `TRUE` if `msg` requires authentication, `FALSE` if not.

### soup_auth_domain_set_filter ()

    void                soup_auth_domain_set_filter         (SoupAuthDomain *domain,
                                                             SoupAuthDomainFilter filter,
                                                             gpointer filter_data,
                                                             GDestroyNotify dnotify);

Adds `filter` as an authentication filter to `domain`. The filter gets a chance to bypass authentication for certain requests that would otherwise require it. Eg, it might check the message's path in some way that is too complicated to do via the other methods, or it might check the message's method, and allow GETs but not PUTs.

The filter function returns `TRUE` if the request should still require authentication, or `FALSE` if authentication is unnecessary for this request.

To help prevent security holes, your filter should return `TRUE` by default, and only return `FALSE` under specifically-tested circumstances, rather than the other way around. Eg, in the example above, where you want to authenticate PUTs but not GETs, you should check if the method is GET and return `FALSE` in that case, and then return `TRUE` for all other methods (rather than returning `TRUE` for PUT and `FALSE` for all other methods). This way if it turned out (now or later) that some paths supported additional methods besides GET and PUT, those methods would default to being NOT allowed for unauthenticated users.

You can also set the filter by setting the `SOUP_AUTH_DOMAIN_FILTER` and `SOUP_AUTH_DOMAIN_FILTER_DATA` properties, which can also be used to set the filter at construct time.

`domain` : | a SoupAuthDomain
`filter` : | the auth filter for `domain`
`filter_data` : | data to pass to `filter`
`dnotify` : | destroy notifier to free `filter_data` when `domain` is destroyed

### soup_auth_domain_get_realm ()

    const char *        soup_auth_domain_get_realm          (SoupAuthDomain *domain);

Gets the realm name associated with `domain`

`domain` : | a SoupAuthDomain
Returns : | `domain`'s realm

### SoupAuthDomainGenericAuthCallback ()

    gboolean            (*SoupAuthDomainGenericAuthCallback)
                                                            (SoupAuthDomain *domain,
                                                             SoupMessage *msg,
                                                             const char *username,
                                                             gpointer user_data);

The prototype for a SoupAuthDomain generic authentication callback.

The callback should look up the user's password, call `soup_auth_domain_check_password()`, and use the return value from that method as its own return value.

In general, for security reasons, it is preferable to use the auth-domain-specific auth callbacks (eg, SoupAuthDomainBasicAuthCallback and SoupAuthDomainDigestAuthCallback), because they don't require keeping a cleartext password database. Most users will use the same password for many different sites, meaning if any site with a cleartext password database is compromised, accounts on other servers might be compromised as well. For many of the cases where SoupServer is used, this is not really relevant, but it may still be worth considering.

`domain` : | a SoupAuthDomain
`msg` : | the SoupMessage being authenticated
`username` : | the username from `msg`
`user_data` : | the data passed to `soup_auth_domain_set_generic_auth_callback()`
Returns : | `TRUE` if `msg` is authenticated, `FALSE` if not.

### soup_auth_domain_set_generic_auth_callback ()

    void                soup_auth_domain_set_generic_auth_callback
                                                            (SoupAuthDomain *domain,
                                                             SoupAuthDomainGenericAuthCallback auth_callback,
                                                             gpointer auth_data,
                                                             GDestroyNotify dnotify);

Sets `auth_callback` as an authentication-handling callback for `domain`. Whenever a request comes in to `domain` which cannot be authenticated via a domain-specific auth callback (eg, SoupAuthDomainDigestAuthCallback), the generic auth callback will be invoked. See SoupAuthDomainGenericAuthCallback for information on what the callback should do.

`domain` : | a SoupAuthDomain
`auth_callback` : | the auth callback
`auth_data` : | data to pass to `auth_callback`
`dnotify` : | destroy notifier to free `auth_data` when `domain` is destroyed

### soup_auth_domain_check_password ()

    gboolean            soup_auth_domain_check_password     (SoupAuthDomain *domain,
                                                             SoupMessage *msg,
                                                             const char *username,
                                                             const char *password);

Checks if `msg` authenticates to `domain` via `username` and `password`. This would normally be called from a SoupAuthDomainGenericAuthCallback.

`domain` : | a SoupAuthDomain
`msg` : | a SoupMessage
`username` : | a username
`password` : | a password
Returns : | whether or not the message is authenticated

### soup_auth_domain_covers ()

    gboolean            soup_auth_domain_covers             (SoupAuthDomain *domain,
                                                             SoupMessage *msg);

Checks if `domain` requires `msg` to be authenticated (according to its paths and filter function). This does not actually look at whether `msg` is authenticated, merely whether or not it needs to be.

This is used by SoupServer internally and is probably of no use to anyone else.

`domain` : | a SoupAuthDomain
`msg` : | a SoupMessage
Returns : | `TRUE` if `domain` requires `msg` to be authenticated

### soup_auth_domain_accepts ()

    char *              soup_auth_domain_accepts            (SoupAuthDomain *domain,
                                                             SoupMessage *msg);

Checks if `msg` contains appropriate authorization for `domain` to accept it. Mirroring `soup_auth_domain_covers()`, this does not check whether or not `domain` cares if `msg` is authorized.

This is used by SoupServer internally and is probably of no use to anyone else.

`domain` : | a SoupAuthDomain
`msg` : | a SoupMessage
Returns : | the username that `msg` has authenticated as, if in fact it has authenticated. `NULL` otherwise.

### soup_auth_domain_challenge ()

    void                soup_auth_domain_challenge          (SoupAuthDomain *domain,
                                                             SoupMessage *msg);

Adds a "WWW-Authenticate" or "Proxy-Authenticate" header to `msg`, requesting that the client authenticate, and sets `msg`'s status accordingly.

This is used by SoupServer internally and is probably of no use to anyone else.

`domain` : | a SoupAuthDomain
`msg` : | a SoupMessage

### SOUP_AUTH_DOMAIN_REALM

    #define SOUP_AUTH_DOMAIN_REALM       "realm"

Alias for the "realm" property. (The realm of this auth domain.)

### SOUP_AUTH_DOMAIN_PROXY

    #define SOUP_AUTH_DOMAIN_PROXY       "proxy"

Alias for the "proxy" property. (Whether or not this is a proxy auth domain.)

### SOUP_AUTH_DOMAIN_ADD_PATH

    #define SOUP_AUTH_DOMAIN_ADD_PATH    "add-path"

Alias for the "add-path" property. (Shortcut for calling `soup_auth_domain_add_path()`.)

### SOUP_AUTH_DOMAIN_REMOVE_PATH

    #define SOUP_AUTH_DOMAIN_REMOVE_PATH "remove-path"

Alias for the "remove-path" property. (Shortcut for calling `soup_auth_domain_remove_path()`.)

### SOUP_AUTH_DOMAIN_FILTER

    #define SOUP_AUTH_DOMAIN_FILTER      "filter"

Alias for the "filter" property. (The SoupAuthDomainFilter for the domain.)

### SOUP_AUTH_DOMAIN_FILTER_DATA

    #define SOUP_AUTH_DOMAIN_FILTER_DATA "filter-data"

Alias for the "filter-data" property. (Data to pass to the SoupAuthDomainFilter.)

### SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK

    #define SOUP_AUTH_DOMAIN_GENERIC_AUTH_CALLBACK "generic-auth-callback"

Alias for the "auth-callback" property. (The SoupAuthDomainGenericAuthCallback.)

### SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA

    #define SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA     "generic-auth-data"

Alias for the "auth-data" property. (The data to pass to the SoupAuthDomainGenericAuthCallback.)

## Property Details

### The `"add-path"` property

      "add-path"                 gchar*                : Write

Add a path covered by this auth domain.

Default value: NULL

### The `"filter"` property

      "filter"                   gpointer              : Read / Write

A filter for deciding whether or not to require authentication.

### The `"filter-data"` property

      "filter-data"              gpointer              : Read / Write

Data to pass to filter.

### The `"generic-auth-callback"` property

      "generic-auth-callback"    gpointer              : Read / Write

An authentication callback that can be used with any SoupAuthDomain subclass.

### The `"generic-auth-data"` property

      "generic-auth-data"        gpointer              : Read / Write

Data to pass to auth callback.

### The `"proxy"` property

      "proxy"                    gboolean              : Read / Write / Construct Only

Whether or not this is a proxy auth domain.

Default value: FALSE

### The `"realm"` property

      "realm"                    gchar*                : Read / Write / Construct Only

The realm of this auth domain.

Default value: NULL

### The `"remove-path"` property

      "remove-path"              gchar*                : Write

Remove a path covered by this auth domain.

Default value: NULL

## See Also

SoupServer