SoupAuthDomain

SoupAuthDomain — Server-side authentication

Functions

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── SoupAuthDomain
        ├── SoupAuthDomainBasic
        ╰── SoupAuthDomainDigest

Includes

#include <libsoup/soup.h>

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.

Functions

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

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.

Parameters

domain

a SoupAuthDomain

 

msg

a SoupMessage

 

Returns

the username that msg has authenticated as, if in fact it has authenticated. NULL otherwise.

[nullable]


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.

[virtual challenge]

Parameters

domain

a SoupAuthDomain

 

msg

a SoupMessage

 

Types and Values

SoupAuthDomain

typedef struct _SoupAuthDomain SoupAuthDomain;

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 “generic-auth-callback” property. (The SoupAuthDomainGenericAuthCallback.)


SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA

#define SOUP_AUTH_DOMAIN_GENERIC_AUTH_DATA     "generic-auth-data"

Alias for the “generic-auth-data” property. (The data to pass to the SoupAuthDomainGenericAuthCallback.)

Property Details

The “add-path” property

  “add-path”                 char *

Add a path covered by this auth domain.

Owner: SoupAuthDomain

Flags: Write

Default value: NULL


The “filter” property

  “filter”                   gpointer

The SoupAuthDomainFilter for the domain

[type SoupAuthDomainFilter]

Owner: SoupAuthDomain

Flags: Read / Write


The “filter-data” property

  “filter-data”              gpointer

Data to pass to filter.

Owner: SoupAuthDomain

Flags: Read / Write


The “generic-auth-callback” property

  “generic-auth-callback”    gpointer

The SoupAuthDomainGenericAuthCallback for the domain

[type SoupAuthDomainGenericAuthCallback]

Owner: SoupAuthDomain

Flags: Read / Write


The “generic-auth-data” property

  “generic-auth-data”        gpointer

Data to pass to auth callback.

Owner: SoupAuthDomain

Flags: Read / Write


The “proxy” property

  “proxy”                    gboolean

Whether or not this is a proxy auth domain.

Owner: SoupAuthDomain

Flags: Read / Write / Construct Only

Default value: FALSE


The “realm” property

  “realm”                    char *

The realm of this auth domain.

Owner: SoupAuthDomain

Flags: Read / Write / Construct Only

Default value: NULL


The “remove-path” property

  “remove-path”              char *

Remove a path covered by this auth domain.

Owner: SoupAuthDomain

Flags: Write

Default value: NULL

See Also

SoupServer