Top |
Functions
void | soup_auth_domain_add_path () |
void | soup_auth_domain_remove_path () |
gboolean | (*SoupAuthDomainFilter) () |
void | soup_auth_domain_set_filter () |
const char * | soup_auth_domain_get_realm () |
gboolean | (*SoupAuthDomainGenericAuthCallback) () |
void | soup_auth_domain_set_generic_auth_callback () |
gboolean | soup_auth_domain_check_password () |
gboolean | soup_auth_domain_covers () |
char * | soup_auth_domain_accepts () |
void | soup_auth_domain_challenge () |
Properties
gchar * | 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 |
gchar * | realm | Read / Write / Construct Only |
gchar * | remove-path | Write |
Types and Values
SoupAuthDomain | |
#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 |
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.
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.
SoupAuthDomainFilter ()
gboolean (*SoupAuthDomainFilter) (SoupAuthDomain *domain
,SoupMessage *msg
,gpointer user_data
);
The prototype for a SoupAuthDomain filter; see
soup_auth_domain_set_filter()
for details.
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.
soup_auth_domain_get_realm ()
const char *
soup_auth_domain_get_realm (SoupAuthDomain *domain
);
Gets the realm name associated with domain
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 |
||
msg |
the SoupMessage being authenticated |
|
username |
the username from |
|
user_data |
the data passed to
|
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.
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.
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.
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.
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.
Types and Values
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” gchar *
Add a path covered by this auth domain.
Flags: Write
Default value: NULL
The “filter”
property
“filter” gpointer
A filter for deciding whether or not to require authentication.
Flags: Read / Write
The “generic-auth-callback”
property
“generic-auth-callback” gpointer
An authentication callback that can be used with any SoupAuthDomain subclass.
Flags: Read / Write
The “generic-auth-data”
property
“generic-auth-data” gpointer
Data to pass to auth callback.
Flags: Read / Write
The “proxy”
property
“proxy” gboolean
Whether or not this is a proxy auth domain.
Flags: Read / Write / Construct Only
Default value: FALSE
The “realm”
property
“realm” gchar *
The realm of this auth domain.
Flags: Read / Write / Construct Only
Default value: NULL
The “remove-path”
property
“remove-path” gchar *
Remove a path covered by this auth domain.
Flags: Write
Default value: NULL