sofia-sip/auth_module.h File Reference


Detailed Description

Authentication verification interface.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>.
Date:
Created: Mon Jul 23 19:21:24 2001 ppessi

#include <sofia-sip/su_tag.h>
#include <sofia-sip/su_wait.h>
#include <sofia-sip/msg_types.h>
#include <sofia-sip/url.h>
#include <sofia-sip/url_tag.h>

Include dependency graph for auth_module.h:

Go to the source code of this file.

Data Structures

struct  auth_status_t
 Authentication operation result. More...
struct  auth_challenger
 Authentication challenge. More...

Defines

#define AUTHTAG_ANY()
 Filter tag matching any AUTHTAG_*().
#define AUTHTAG_MODULE(x)
 Pointer to an authentication server (auth_mod_t).
#define AUTHTAG_METHOD(x)
 Authentication scheme used by authentication module.
#define AUTHTAG_REALM(x)
 Authentication realm used by authentication server.
#define AUTHTAG_OPAQUE(x)
 Opaque authentication data always included in challenge.
#define AUTHTAG_DB(x)
 Name of authentication database used by authentication server.
#define AUTHTAG_QOP(x)
 Quality-of-protection used by digest authentication.
#define AUTHTAG_ALGORITHM(x)
 Algorithm used by digest authentication.
#define AUTHTAG_EXPIRES(x)
 Nonce lifetime.
#define AUTHTAG_NEXT_EXPIRES(x)
 Lifetime for nextnonce, 0 disables nextnonce.
#define AUTHTAG_BLACKLIST(x)
 Extra delay when responding if provided invalid credentials or nonce.
#define AUTHTAG_FORBIDDEN(x)
 Respond with 403 Forbidden if given invalid credentials.
#define AUTHTAG_ANONYMOUS(x)
 Allow anonymous access.
#define AUTHTAG_FAKE(x)
 Fake authentication procedure - do not check result.
#define AUTHTAG_HSS(x)
 HSS client structure.
#define AUTHTAG_REMOTE(x)
 Remote authenticator URL.
#define AUTHTAG_ALLOW(x)
 Comma-separated list of methods never challenged.
#define AUTHTAG_FAKE(x)
 Fake authentication procedure - do not check result.
#define AUTHTAG_MASTER_KEY(x)
 Master key in base64 for the authentication module.
#define AUTHTAG_CACHE_USERS(x)
 Cache time for authentication data.
#define AUTHTAG_CACHE_ERRORS(x)
 Cache time for errors.

Typedefs

typedef auth_status_t auth_status_t
 Authentication operation.
typedef auth_scheme const auth_scheme_t
 Virtual table for authentication plugin.
typedef auth_plugin_t auth_plugin_t
 Opaque data used by authentication plugin module.
typedef auth_splugin_t auth_splugin_t
 Opaque user data used by plugin module.
typedef auth_uplugin_t auth_uplugin_t
 Opaque authentication operation data used by plugin module.
typedef void auth_callback_t (auth_magic_t *, auth_status_t *)
 Callback from completeted asynchronous authentication operation.
typedef auth_challenger auth_challenger_t
 Authentication challenge.

Functions

int auth_mod_register_plugin (auth_scheme_t *asch)
 Register an authentication plugin.
auth_mod_tauth_mod_create (su_root_t *root, tag_type_t, tag_value_t,...)
 Create an authentication plugin module.
void auth_mod_destroy (auth_mod_t *)
 Destroy (a reference to) an authentication module.
auth_mod_tauth_mod_ref (auth_mod_t *am)
 Create a new reference to authentication module.
void auth_mod_unref (auth_mod_t *am)
 Destroy a reference to an authentication module.
char const * auth_mod_name (auth_mod_t *am)
 Get authenticatin module name.
void auth_mod_verify (auth_mod_t *am, auth_status_t *as, msg_auth_t *credentials, auth_challenger_t const *ach)
 Authenticate user.
void auth_mod_challenge (auth_mod_t *am, auth_status_t *as, auth_challenger_t const *ach)
 Make a challenge header.
void auth_mod_cancel (auth_mod_t *am, auth_status_t *as)
 Cancel asynchronous authentication.


Define Documentation

#define AUTHTAG_ALGORITHM (  ) 

Algorithm used by digest authentication.

#define AUTHTAG_ALLOW (  ) 

Comma-separated list of methods never challenged.

#define AUTHTAG_ANONYMOUS (  ) 

Allow anonymous access.

#define AUTHTAG_BLACKLIST (  ) 

Extra delay when responding if provided invalid credentials or nonce.

#define AUTHTAG_CACHE_ERRORS (  ) 

Cache time for errors.

#define AUTHTAG_CACHE_USERS (  ) 

Cache time for authentication data.

#define AUTHTAG_DB (  ) 

Name of authentication database used by authentication server.

#define AUTHTAG_EXPIRES (  ) 

Nonce lifetime.

#define AUTHTAG_FAKE (  ) 

Fake authentication procedure - do not check result.

#define AUTHTAG_FAKE (  ) 

Fake authentication procedure - do not check result.

#define AUTHTAG_FORBIDDEN (  ) 

Respond with 403 Forbidden if given invalid credentials.

#define AUTHTAG_HSS (  ) 

HSS client structure.

#define AUTHTAG_MASTER_KEY (  ) 

Master key in base64 for the authentication module.

#define AUTHTAG_METHOD (  ) 

Authentication scheme used by authentication module.

#define AUTHTAG_MODULE (  ) 

Pointer to an authentication server (auth_mod_t).

#define AUTHTAG_NEXT_EXPIRES (  ) 

Lifetime for nextnonce, 0 disables nextnonce.

#define AUTHTAG_OPAQUE (  ) 

Opaque authentication data always included in challenge.

#define AUTHTAG_QOP (  ) 

Quality-of-protection used by digest authentication.

#define AUTHTAG_REALM (  ) 

Authentication realm used by authentication server.

#define AUTHTAG_REMOTE (  ) 

Remote authenticator URL.


Typedef Documentation

typedef void auth_callback_t(auth_magic_t *, auth_status_t *)

Callback from completeted asynchronous authentication operation.

typedef struct auth_challenger auth_challenger_t

Authentication challenge.

This structure defines what kind of response and challenge header is returned to the user. For example, a server authentication is implemented with 401 response code and phrase along with header class for WWW-Authenticate header in the ach structure.

typedef struct auth_plugin_t auth_plugin_t

Opaque data used by authentication plugin module.

typedef struct auth_scheme const auth_scheme_t

Virtual table for authentication plugin.

typedef struct auth_splugin_t auth_splugin_t

Opaque user data used by plugin module.

typedef struct auth_status_t auth_status_t

Authentication operation.

typedef struct auth_uplugin_t auth_uplugin_t

Opaque authentication operation data used by plugin module.


Function Documentation

void auth_mod_cancel ( auth_mod_t am,
auth_status_t as 
)

Cancel asynchronous authentication.

The auth_mod_cancel() function cancels a pending authentication. Application can reclaim the authentication status, credential and challenger objects by using auth_mod_cancel().

void auth_mod_challenge ( auth_mod_t am,
auth_status_t as,
auth_challenger_t const *  ach 
)

Make a challenge header.

This function invokes plugin-specific member function generating a challenge header. Client uses the challenge header contents when prompting the user for a username and password then generates its credential header using the parameters given in the challenge header.

Parameters:
am pointer to authentication module object
as pointer to authentication status structure (return-value)
ach pointer to a structure describing challenge
The auth_mod_challenge() returns the challenge header, appropriate response code and reason phrase in the auth_status_t structure. The auth_mod_challenge() is currently always synchronous function.

auth_mod_t* auth_mod_create ( su_root_t root,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Create an authentication plugin module.

The function auth_mod_create() creates a module used to authenticate the requests.

Parameters:
root pointer to a su_root_t object
tag,value,... tagged argument list
Related Tags:
AUTHTAG_METHOD(), AUTHTAG_REALM(), AUTHTAG_DB(), AUTHTAG_ALLOW(), AUTHTAG_QOP(), AUTHTAG_ALGORITHM(), AUTHTAG_EXPIRES(), AUTHTAG_BLACKLIST(), AUTHTAG_FORBIDDEN(), AUTHTAG_ANONYMOUS(), AUTHTAG_REMOTE().

void auth_mod_destroy ( auth_mod_t am  ) 

Destroy (a reference to) an authentication module.

char const* auth_mod_name ( auth_mod_t am  ) 

Get authenticatin module name.

Since:
New in 1.12.4.

auth_mod_t* auth_mod_ref ( auth_mod_t am  ) 

Create a new reference to authentication module.

int auth_mod_register_plugin ( auth_scheme_t asch  ) 

Register an authentication plugin.

Return values:
0 when successful
-1 upon an error

void auth_mod_unref ( auth_mod_t am  ) 

Destroy a reference to an authentication module.

void auth_mod_verify ( auth_mod_t am,
auth_status_t as,
msg_auth_t *  credentials,
auth_challenger_t const *  ach 
)

Authenticate user.

The function auth_mod_method() invokes scheme-specific authentication operation where the user's credentials are checked using scheme-specific method. The authentication result along with an optional challenge header is stored in the as structure.

Parameters:
am pointer to authentication module object [in]
as pointer to authentication status structure [in/out]
credentials pointer to a header with user's credentials [in]
ach pointer to a structure describing challenge [in]
The ach structure defines what kind of response and challenge header is returned to the user. For example, a server authentication is implemented with 401 response code and phrase along with WWW-Authenticate header template in the ach structure.

The auth_mod_method() returns the authentication result in the auth_mod_t as structure. The as->as_status describes the result as follows:

When the authentication is left pending, the client must set the as_callback pointer in as structure to an appropriate callback function. The callback is invoked when the authentication is completed, either successfully or with an error.

Note that the authentication module may generate a new challenge each time authentication is used (e.g., Digest using MD5 algorithm). Such a challenge header is stored in the as->as_response return-value field.

Note:
The authentication plugin may use the given reference to as, credentials and ach structures until the asynchronous authentication completes. Therefore, they should not be allocated from stack unless application uses strictly synchronous authentication schemes only (Basic and Digest).

This function should be called auth_mod_check().


Sofia-SIP 1.12.6 - Copyright (C) 2006 Nokia Corporation. All rights reserved. Licensed under the terms of the GNU Lesser General Public License.