SoupAuth

SoupAuth — HTTP client-side authentication support

Functions

Properties

char * authority Read / Write
gboolean is-authenticated Read
gboolean is-cancelled Read
gboolean is-for-proxy Read / Write
char * realm Read / Write
char * scheme-name Read

Types and Values

Object Hierarchy

    GObject
    ╰── SoupAuth
        ├── SoupAuthBasic
        ├── SoupAuthDigest
        ╰── SoupConnectionAuth
            ├── SoupAuthNTLM
            ╰── SoupAuthNegotiate

Includes

#include <libsoup/soup.h>

Description

SoupAuth objects store the authentication data associated with a given bit of web space. They are created automatically by SoupSession.

Functions

soup_auth_new ()

SoupAuth *
soup_auth_new (GType type,
               SoupMessage *msg,
               const char *auth_header);

Creates a new SoupAuth of type type with the information from msg and auth_header .

This is called by SoupSession; you will normally not create auths yourself.

Parameters

type

the type of auth to create (a subtype of SoupAuth)

 

msg

the SoupMessage the auth is being created for

 

auth_header

the WWW-Authenticate/Proxy-Authenticate header

 

Returns

the new SoupAuth, or NULL if it could not be created.

[nullable]


soup_auth_update ()

gboolean
soup_auth_update (SoupAuth *auth,
                  SoupMessage *msg,
                  const char *auth_header);

Updates auth with the information from msg and auth_header , possibly un-authenticating it. As with soup_auth_new(), this is normally only used by SoupSession.

Parameters

auth

a SoupAuth

 

msg

the SoupMessage auth is being updated for

 

auth_header

the WWW-Authenticate/Proxy-Authenticate header

 

Returns

TRUE if auth is still a valid (but potentially unauthenticated) SoupAuth. FALSE if something about auth_params could not be parsed or incorporated into auth at all.


soup_auth_negotiate_supported ()

gboolean
soup_auth_negotiate_supported (void);

Indicates whether libsoup was built with GSSAPI support. If this is FALSE, SOUP_TYPE_AUTH_NEGOTIATE will still be defined and can still be added to a SoupSession, but libsoup will never attempt to actually use this auth type.


soup_auth_is_for_proxy ()

gboolean
soup_auth_is_for_proxy (SoupAuth *auth);

Tests whether or not auth is associated with a proxy server rather than an "origin" server.

Parameters

auth

a SoupAuth

 

Returns

TRUE or FALSE


soup_auth_get_scheme_name ()

const char *
soup_auth_get_scheme_name (SoupAuth *auth);

Returns auth 's scheme name. (Eg, "Basic", "Digest", or "NTLM")

Parameters

auth

a SoupAuth

 

Returns

the scheme name


soup_auth_get_authority ()

const char *
soup_auth_get_authority (SoupAuth *auth);

Returns the authority (host:port) that auth is associated with.

Parameters

auth

a SoupAuth

 

Returns

the authority


soup_auth_get_realm ()

const char *
soup_auth_get_realm (SoupAuth *auth);

Returns auth 's realm. This is an identifier that distinguishes separate authentication spaces on a given server, and may be some string that is meaningful to the user. (Although it is probably not localized.)

Parameters

auth

a SoupAuth

 

Returns

the realm name


soup_auth_get_info ()

char *
soup_auth_get_info (SoupAuth *auth);

Gets an opaque identifier for auth , for use as a hash key or the like. SoupAuth objects from the same server with the same identifier refer to the same authentication domain (eg, the URLs associated with them take the same usernames and passwords).

Parameters

auth

a SoupAuth

 

Returns

the identifier


soup_auth_authenticate ()

void
soup_auth_authenticate (SoupAuth *auth,
                        const char *username,
                        const char *password);

Call this on an auth to authenticate it; normally this will cause the auth's message to be requeued with the new authentication info.

Parameters

auth

a SoupAuth

 

username

the username provided by the user or client

 

password

the password provided by the user or client

 

soup_auth_can_authenticate ()

gboolean
soup_auth_can_authenticate (SoupAuth *auth);

Tests if auth is able to authenticate by providing credentials to the soup_auth_authenticate().

Parameters

auth

a SoupAuth

 

Returns

TRUE if auth is able to accept credentials.


soup_auth_is_authenticated ()

gboolean
soup_auth_is_authenticated (SoupAuth *auth);

Tests if auth has been given a username and password

Parameters

auth

a SoupAuth

 

Returns

TRUE if auth has been given a username and password


soup_auth_is_ready ()

gboolean
soup_auth_is_ready (SoupAuth *auth,
                    SoupMessage *msg);

Tests if auth is ready to make a request for msg with. For most auths, this is equivalent to soup_auth_is_authenticated(), but for some auth types (eg, NTLM), the auth may be sendable (eg, as an authentication request) even before it is authenticated.

Parameters

auth

a SoupAuth

 

msg

a SoupMessage

 

Returns

TRUE if auth is ready to make a request with.


soup_auth_cancel ()

void
soup_auth_cancel (SoupAuth *auth);

Call this on an auth to cancel it. You need to cancel an auth to complete an asynchronous authenticate operation when no credentials are provided (soup_auth_authenticate() is not called). The SoupAuth will be cancelled on dispose if it hans't been authenticated.

Parameters

auth

a SoupAuth

 

soup_auth_is_cancelled ()

gboolean
soup_auth_is_cancelled (SoupAuth *auth);

Tests if auth has been cancelled

Parameters

auth

a SoupAuth

 

Returns

TRUE if auth has been cancelled


soup_auth_get_authorization ()

char *
soup_auth_get_authorization (SoupAuth *auth,
                             SoupMessage *msg);

Generates an appropriate "Authorization" header for msg . (The session will only call this if soup_auth_is_authenticated() returned TRUE.)

Parameters

auth

a SoupAuth

 

msg

the SoupMessage to be authorized

 

Returns

the "Authorization" header, which must be freed.


soup_auth_get_protection_space ()

GSList *
soup_auth_get_protection_space (SoupAuth *auth,
                                GUri *source_uri);

Returns a list of paths on the server which auth extends over. (All subdirectories of these paths are also assumed to be part of auth 's protection space, unless otherwise discovered not to be.)

Parameters

auth

a SoupAuth

 

source_uri

the URI of the request that auth was generated in response to.

 

Returns

the list of paths, which can be freed with soup_auth_free_protection_space().

[element-type utf8][transfer full]


soup_auth_free_protection_space ()

void
soup_auth_free_protection_space (SoupAuth *auth,
                                 GSList *space);

Frees space .

[skip]

Parameters

auth

a SoupAuth

 

space

the return value from soup_auth_get_protection_space()

 

Types and Values

SoupAuth

typedef struct _SoupAuth SoupAuth;

The abstract base class for handling authentication. Specific HTTP Authentication mechanisms are implemented by its subclasses, but applications never need to be aware of the specific subclasses being used.


SOUP_TYPE_AUTH_BASIC

#define SOUP_TYPE_AUTH_BASIC (soup_auth_basic_get_type ())

A GType corresponding to HTTP "Basic" authentication. SoupSessions support this by default; if you want to disable support for it, call soup_session_remove_feature_by_type(), passing SOUP_TYPE_AUTH_BASIC.


SOUP_TYPE_AUTH_DIGEST

#define SOUP_TYPE_AUTH_DIGEST (soup_auth_digest_get_type ())

A GType corresponding to HTTP "Digest" authentication. SoupSessions support this by default; if you want to disable support for it, call soup_session_remove_feature_by_type(), passing SOUP_TYPE_AUTH_DIGEST.


SOUP_TYPE_AUTH_NTLM

#define SOUP_TYPE_AUTH_NTLM (soup_auth_ntlm_get_type ())

A GType corresponding to HTTP-based NTLM authentication. SoupSessions do not support this type by default; if you want to enable support for it, call soup_session_add_feature_by_type(), passing SOUP_TYPE_AUTH_NTLM.


SOUP_TYPE_AUTH_NEGOTIATE

#define SOUP_TYPE_AUTH_NEGOTIATE (soup_auth_negotiate_get_type ())

A GType corresponding to HTTP-based GSS-Negotiate authentication. SoupSessions do not support this type by default; if you want to enable support for it, call soup_session_add_feature_by_type(), passing SOUP_TYPE_AUTH_NEGOTIATE.

This auth type will only work if libsoup was compiled with GSSAPI support; you can check soup_auth_negotiate_supported() to see if it was.

Property Details

The “authority” property

  “authority”                char *

The authority (host:port) being authenticated to.

Owner: SoupAuth

Flags: Read / Write

Default value: NULL


The “is-authenticated” property

  “is-authenticated”         gboolean

Whether or not the auth has been authenticated.

Owner: SoupAuth

Flags: Read

Default value: FALSE


The “is-cancelled” property

  “is-cancelled”             gboolean

An alias for the “is-cancelled” property. (Whether or not the auth has been cancelled.)

Owner: SoupAuth

Flags: Read

Default value: FALSE


The “is-for-proxy” property

  “is-for-proxy”             gboolean

Whether or not the auth is for a proxy server.

Owner: SoupAuth

Flags: Read / Write

Default value: FALSE


The “realm” property

  “realm”                    char *

The authentication realm.

Owner: SoupAuth

Flags: Read / Write

Default value: NULL


The “scheme-name” property

  “scheme-name”              char *

The authentication scheme name.

Owner: SoupAuth

Flags: Read

Default value: NULL

See Also

SoupSession