libsoup Reference Manual: SoupAuthDomainDigest

## SoupAuthDomainDigest SoupAuthDomainDigest — Server-side "Digest" authentication |

## Functions

SoupAuthDomain * | soup_auth_domain_digest_new ()
char * | (*SoupAuthDomainDigestAuthCallback) ()
void | soup_auth_domain_digest_set_auth_callback ()
char * | soup_auth_domain_digest_encode_password ()

## Properties

gpointer | auth-callback | Read / Write
gpointer | auth-data | Read / Write

## Types and Values

| SoupAuthDomainDigest
#define | SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK
#define | SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA

## Object Hierarchy

        GObject
        ╰── SoupAuthDomain
            ╰── SoupAuthDomainDigest

## Includes

    #include <libsoup/soup.h>

## Description

SoupAuthDomainDigest handles the server side of HTTP "Digest" authentication.

## Functions

### soup_auth_domain_digest_new ()

    SoupAuthDomain *
    soup_auth_domain_digest_new (const char *optname1,
                                 ...);

Creates a SoupAuthDomainDigest. You must set the `SOUP_AUTH_DOMAIN_REALM` parameter, to indicate the realm name to be returned with the authentication challenge to the client. Other parameters are optional.

#### Parameters

optname1 | name of first option, or `NULL` |
... | option name/value pairs |

#### Returns

the new SoupAuthDomain

### SoupAuthDomainDigestAuthCallback ()

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

Callback used by SoupAuthDomainDigest for authentication purposes. The application should look up `username` in its password database, and return the corresponding encoded password (see `soup_auth_domain_digest_encode_password()`).

#### Parameters

domain | the domain |
msg | the message being authenticated |
username | the username provided by the client |
user_data | the data passed to `soup_auth_domain_digest_set_auth_callback()` |

#### Returns

the encoded password, or `NULL` if `username` is not a valid user. `domain` will free the password when it is done with it.

[nullable]

### soup_auth_domain_digest_set_auth_callback ()

    void
    soup_auth_domain_digest_set_auth_callback
                                   (SoupAuthDomain *domain,
                                    SoupAuthDomainDigestAuthCallback callback,
                                    gpointer user_data,
                                    GDestroyNotify dnotify);

Sets the callback that `domain` will use to authenticate incoming requests. For each request containing authorization, `domain` will invoke the callback, and then either accept or reject the request based on `callback` 's return value.

You can also set the auth callback by setting the `SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK` and `SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA` properties, which can also be used to set the callback at construct time.

#### Parameters

domain | the domain |
callback | the callback |
user_data | data to pass to `auth_callback` |
dnotify | destroy notifier to free `user_data` when `domain` is destroyed |

### soup_auth_domain_digest_encode_password ()

    char *
    soup_auth_domain_digest_encode_password
                                   (const char *username,
                                    const char *realm,
                                    const char *password);

Encodes the username/realm/password triplet for Digest authentication. (That is, it returns a stringified MD5 hash of `username` , `realm` , and `password` concatenated together). This is the form that is needed as the return value of SoupAuthDomainDigest's auth handler.

For security reasons, you should store the encoded hash, rather than storing the cleartext password itself and calling this method only when you need to verify it. This way, if your server is compromised, the attackers will not gain access to cleartext passwords which might also be usable at other sites. (Note also that the encoded password returned by this method is identical to the encoded password stored in an Apache .htdigest file.)

#### Parameters

username | a username |
realm | an auth realm name |
password | the password for `username` in `realm` |

#### Returns

the encoded password

## Types and Values

### SoupAuthDomainDigest

    typedef struct _SoupAuthDomainDigest SoupAuthDomainDigest;

### SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK

    #define SOUP_AUTH_DOMAIN_DIGEST_AUTH_CALLBACK "auth-callback"

Alias for the “auth-callback” property. (The SoupAuthDomainDigestAuthCallback.)

### SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA

    #define SOUP_AUTH_DOMAIN_DIGEST_AUTH_DATA     "auth-data"

Alias for the “auth-callback” property. (The SoupAuthDomainDigestAuthCallback.)

## Property Details

### The `“auth-callback”` property

      “auth-callback”            gpointer

Password-finding callback.

Flags: Read / Write

### The `“auth-data”` property

      “auth-data”                gpointer

Data to pass to authentication callback.

Flags: Read / Write