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_MAX_NCOUNT(x)

Maximum nonce count allowed.

#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_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)

Check that user exists, don't do authentication.

#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_t * auth_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_t * auth_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 ( x )

Algorithm used by digest authentication.
The tag AUTHTAG_ALGORITHM() specifies the qop scheme to be used by the digest authentication.

#define AUTHTAG_ALLOW ( x )

Comma-separated list of methods never challenged.
The tag AUTHTAG_ALLOW() takes its argument a string containing a comma-separated list of methods, for example,
AUTHTAG_ALLOW("ACK, BYE, CANCEL").
The specified methods are not challenged by the authentication module. For example, this may include SIP ACK method or SIP methods only used within an already established dialog.

#define AUTHTAG_ANONYMOUS ( x )

Allow anonymous access.
When given a true argument, the tag AUTHTAG_ANONYMOUS() allows authentication module to accept the account "anonymous" with an empty password. The auth_status_t::as_anonymous flag is set in auth_status_t structure after anonymous authentication.

#define AUTHTAG_BLACKLIST ( x )

Extra delay when responding if provided invalid credentials or nonce.
The tag AUTHTAG_BLACKLIST() specifies the time the server delays its response if it is given bad credentials or malformed nonce. The default time is 5 seconds.

Todo:
Implement delayed response.

#define AUTHTAG_CACHE_ERRORS ( x )

Cache time for errors.
The tag AUTHTAG_CACHE_ERRORS() specifies the lifetime in seconds for errors in the local authentication data cache. Note that the errors generated locally (e.g., because of connectivity problem with authentication server) have maximum lifetime of 2 minutes.

#define AUTHTAG_CACHE_USERS ( x )

Cache time for authentication data.
The tag AUTHTAG_CACHE_USERS() specifies how many seconds the user data is cached locally. Default value is typically 30 minutes.

#define AUTHTAG_DB ( x )

Name of authentication database used by authentication server.
The tag AUTHTAG_DB() specifies the file name used to store the authentication data. The file contains triplets as follows:

user:password:realm

Note:
Currently, the passwords are stored as plaintext.

#define AUTHTAG_EXPIRES ( x )

Nonce lifetime.
The tag AUTHTAG_EXPIRES() specifies the time in seconds that a nonce is considered valid. If 0, the nonce lifetime unbounded. The default time is 3600 seconds.

#define AUTHTAG_FAKE ( x )

Check that user exists, don't do authentication.
When given a true argument, the tag AUTHTAG_FAKE() causes authentication module to allow access with any password when the username is valid. The auth_status_t::as_fake flag is set in auth_status_t structure after a fake authentication.

#define AUTHTAG_FORBIDDEN ( x )

Respond with 403 Forbidden if given invalid credentials.
When given a true argument, the tag AUTHTAG_FORBIDDEN() specifies that the server responds with 403 Forbidden (instead of 401/407) when it receives bad credentials.

#define AUTHTAG_MASTER_KEY ( x )

Master key in base64 for the authentication module.
The tag AUTHTAG_MASTER_KEY() specifies a private master key that can be used by the authentication module for various purposes (for instance, validating that nonces are really generated by it).

#define AUTHTAG_MAX_NCOUNT ( x )

Maximum nonce count allowed.
The tag AUTHTAG_MAX_NCOUNT() specifies the maximum number of times a nonce should be used.

Todo:
Count actual usages and don't trust "nc" parameter only.

#define AUTHTAG_METHOD ( x )

Authentication scheme used by authentication module.
The tag AUTHTAG_METHOD() specifies the authentication module and scheme to be used by the auth_module. The name can specify a basic authentication module, like "Digest" or "Basic", or an plugin module, like "SGMF+Digest".

See also:
See <sofia-sip/auth_plugin.h> for plugin interface.

#define AUTHTAG_MODULE ( x )

Pointer to an authentication server (auth_mod_t).
The tag item AUTHTAG_MODULE() contains pointer to an authentication server module. It is used to pass an already initialized authentication module to a server object (like web server or registrar object).

#define AUTHTAG_NEXT_EXPIRES ( x )

Lifetime for nextnonce, 0 disables nextnonce.
The tag AUTHTAG_NEXT_EXPIRES() specifies the time in seconds that a nextnonce sent in Authentication-Info header is considered valid. If 0, the nonce lifetime is unbounded. The default time is 3600 seconds.

#define AUTHTAG_OPAQUE ( x )

Opaque authentication data always included in challenge.
The tag authtag_opaque is used to pass opaque data to the auth_module. The opaque data will be included in all the challenges (however, the data is prefixed with a "." and other opaque data used by the algorithms.
Default Value "".

#define AUTHTAG_QOP ( x )

Quality-of-protection used by digest authentication.
The tag AUTHTAG_QOP() specifies the qop scheme to be used by the digest authentication.

#define AUTHTAG_REALM ( x )

Authentication realm used by authentication server.
The tag authtag_method specifies the authentication realm used by the auth_module. For servers, the domain name in the request URI is inserted in the realm returned to the client if the realm string contains an asterisk "*". Only the first asterisk is replaced by request domain name.
Default Value "*".

#define AUTHTAG_REMOTE ( x )

Remote authenticator URL.
The tag AUTHTAG_REMOTE() is used to specify URL for remote authenticator. The meaning of the URL is specific to the authentication module. The authentication module is selected by AUTHTAG_METHOD().

Typedef Documentation

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.

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().

char const* auth_mod_name ( auth_mod_t * am )

Get authenticatin module name.

Since:
New in 1.12.4.

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_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:

as->as_status == 0 authentication is successful
as->as_status == 100 authentication is pending
as->as_status >= 400 authentication fails, return as_status as an error code to client

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().


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_MAX_NCOUNT(x)
	Maximum nonce count allowed.
#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_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)
	Check that user exists, don't do authentication.
#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_t *	auth_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_t *	auth_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.