## SoupAuth

SoupAuth — HTTP Authentication support

## Synopsis

                        SoupAuth;
                        SoupAuthBasic;
                        SoupAuthDigest;
    SoupAuth*           soup_auth_new_from_header_list      (const GSList *vals);
    const char*         soup_auth_get_scheme_name           (SoupAuth *auth);
    const char*         soup_auth_get_realm                 (SoupAuth *auth);
    void                soup_auth_authenticate              (SoupAuth *auth,
                                                             const char *username,
                                                             const char *password);
    gboolean            soup_auth_is_authenticated          (SoupAuth *auth);
    char*               soup_auth_get_authorization         (SoupAuth *auth,
                                                             SoupMessage *msg);
    GSList*             soup_auth_get_protection_space      (SoupAuth *auth,
                                                             const SoupUri *source_uri);
    void                soup_auth_free_protection_space     (SoupAuth *auth,
                                                             GSList *space);

## Object Hierarchy

      GObject
       +----SoupAuth
             +----SoupAuthBasic
             +----SoupAuthDigest

      GObject
       +----SoupAuth
             +----SoupAuthBasic

      GObject
       +----SoupAuth
             +----SoupAuthDigest

## Description

SoupAuth objects store the authentication data associated with a given bit of webspace. They are created and maintained automatically by SoupSession.

## Details

### SoupAuth

    typedef struct _SoupAuth SoupAuth;

The abstract base class for handling authentication. Specific HTTP Authentication mechanisms are implemented by its subclasses. (NTLM authentication, which works quite differently from normal HTTP authentication, is handled by SoupConnectionNTLM.)

### SoupAuthBasic

    typedef struct _SoupAuthBasic SoupAuthBasic;

An object representing Basic HTTP authentication.

### SoupAuthDigest

    typedef struct _SoupAuthDigest SoupAuthDigest;

An object representing Digest HTTP authentication.

### soup_auth_new_from_header_list ()

    SoupAuth*           soup_auth_new_from_header_list      (const GSList *vals);

Creates a SoupAuth value based on the strongest available supported auth type in `vals`.

`vals` : | a list of WWW-Authenticate headers from a server response
Returns : | the new SoupAuth, or `NULL` if none could be created.

### soup_auth_get_scheme_name ()

    const char*         soup_auth_get_scheme_name           (SoupAuth *auth);

Returns `auth`'s scheme name. (Eg, "Basic")

`auth` : | a SoupAuth
Returns : | the scheme name

### soup_auth_get_realm ()

    const char*         soup_auth_get_realm                 (SoupAuth *auth);

Returns `auth`'s realm.

`auth` : | a SoupAuth
Returns : | the realm name

### soup_auth_authenticate ()

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

This is called by the session after requesting a username and password from the application. `auth` will take the information and do whatever scheme-specific processing is needed.

`auth` : | a SoupAuth
`username` : | the username provided by the user or client
`password` : | the password provided by the user or client

### soup_auth_is_authenticated ()

    gboolean            soup_auth_is_authenticated          (SoupAuth *auth);

Tests if `auth` has been given a username and password

`auth` : | a SoupAuth
Returns : | `TRUE` if `auth` has been given a username and password

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

`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,
                                                             const SoupUri *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.)

`auth` : | a SoupAuth
`source_uri` : | the URI of the request that `auth` was generated in response to.
Returns : | the list of paths, which must be freed with `soup_auth_free_protection_space()`.

### soup_auth_free_protection_space ()

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

Frees `space`.

`auth` : | a SoupAuth
`space` : | the return value from `soup_auth_get_protection_space()`

## See Also

SoupSession, SoupConnectionNTLM