auth_module.c File Reference


Detailed Description

Authentication verification module.

The authentication module provides server or proxy-side authentication verification for network elements like registrars, presence servers, and proxies.

Author:
Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>.
Date:
Created: Wed Apr 11 15:14:03 2001 ppessi

#include "config.h"
#include <stddef.h>
#include <stdlib.h>
#include <string.h>
#include <stdio.h>
#include <assert.h>
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <sofia-sip/auth_digest.h>
#include "iptsec_debug.h"
#include <sofia-sip/su_debug.h>
#include <sofia-sip/su_wait.h>
#include <sofia-sip/su_alloc.h>
#include <sofia-sip/su_tagarg.h>
#include <sofia-sip/base64.h>
#include <sofia-sip/su_md5.h>
#include <sofia-sip/msg_parser.h>
#include <sofia-sip/msg_date.h>
#include "sofia-sip/auth_module.h"
#include "sofia-sip/auth_plugin.h"

Include dependency graph for auth_module.c:


Functions

auth_mod_tauth_mod_alloc (auth_scheme_t *scheme, tag_type_t tag, tag_value_t value,...)
 Allocate an authentication module instance.
int auth_init_default (auth_mod_t *am, auth_scheme_t *base, su_root_t *root, tag_type_t tag, tag_value_t value,...)
 Initialize an authentication module instance.
void auth_mod_destroy (auth_mod_t *am)
 Destroy (a reference to) an authentication module.
void auth_destroy_default (auth_mod_t *am)
 Default destroy method.
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.
void auth_cancel_default (auth_mod_t *am, auth_status_t *as)
 Default cancel method.
void auth_method_basic (auth_mod_t *am, auth_status_t *as, msg_auth_t *au, auth_challenger_t const *ach)
 Basic scheme.
void auth_challenge_basic (auth_mod_t *am, auth_status_t *as, auth_challenger_t const *ach)
 Construct a challenge header for Basic authentication scheme.
void auth_method_digest (auth_mod_t *am, auth_status_t *as, msg_auth_t *au, auth_challenger_t const *ach)
 Authenticate a request with Digest authentication scheme.
void auth_check_digest (auth_mod_t *am, auth_status_t *as, auth_response_t *ar, auth_challenger_t const *ach)
 Verify digest authentication.
void auth_challenge_digest (auth_mod_t *am, auth_status_t *as, auth_challenger_t const *ach)
 Construct a challenge header for Digest authentication scheme.
void auth_info_digest (auth_mod_t *am, auth_status_t *as, auth_challenger_t const *ach)
 Construct a info header for Digest authentication scheme.
auth_passwd_tauth_mod_getpass (auth_mod_t *am, char const *user, char const *realm)
 Get an passwd entry for user.
auth_passwd_tauth_mod_addpass (auth_mod_t *am, char const *user, char const *realm)
 Add a password entry.
int auth_readdb (auth_mod_t *am)
 Read authentication database.
int auth_readdb_if_needed (auth_mod_t *am)
 Read authentication database only when needed.
int auth_allow_check (auth_mod_t *am, auth_status_t *as)
 Check if request method is on always-allowed list.
msg_auth_t * auth_mod_credentials (msg_auth_t *auth, char const *scheme, char const *realm)
 Find a credential header with matching scheme and realm.
msg_auth_t * auth_digest_credentials (msg_auth_t *auth, char const *realm, char const *opaque)
 Digest scheme.
isize_t auth_generate_digest_nonce (auth_mod_t *am, char buffer[], size_t bsize, int nextnonce, msg_time_t now)
 Generate nonce parameter.
int auth_validate_digest_nonce (auth_mod_t *am, auth_status_t *as, auth_response_t *ar, msg_time_t now)
 Validate nonce parameter.
void auth_md5_hmac_init (auth_mod_t *am, struct su_md5_t *imd5)
 Init md5 for MD5-based HMAC.

Function Documentation

int auth_allow_check ( auth_mod_t am,
auth_status_t as 
)

Check if request method is on always-allowed list.

Returns:
0 if allowed

1 otherwise

void auth_cancel_default ( auth_mod_t am,
auth_status_t as 
)

Default cancel method.

The auth_cancel_default() is the default member function called by auth_mod_cancel().

void auth_destroy_default ( auth_mod_t am  ) 

Default destroy method.

The auth_destroy_default() is the default member function called by auth_mod_destroy().

isize_t auth_generate_digest_nonce ( auth_mod_t am,
char  buffer[],
size_t  bsize,
int  nextnonce,
msg_time_t  now 
)

Generate nonce parameter.

Parameters:
am pointer to authentication module object
buffer string buffer for nonce [OUT]
bsize size of buffer [IN]
nextnonce true if this is a "nextnonce" [IN]
now current time [IN]

int auth_init_default ( auth_mod_t am,
auth_scheme_t base,
su_root_t root,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Initialize an authentication module instance.

The function auth_mod_init_default() initializes an authentication module object used to authenticate the requests.

Parameters:
am 
base 
root 
tag,value,... tagged argument list
Related Tags:
AUTHTAG_REALM(), AUTHTAG_OPAQUE(), AUTHTAG_DB(), AUTHTAG_QOP(), AUTHTAG_ALGORITHM(), AUTHTAG_EXPIRES(), AUTHTAG_NEXT_EXPIRES(), AUTHTAG_BLACKLIST(), AUTHTAG_FORBIDDEN(), AUTHTAG_ANONYMOUS(), AUTHTAG_FAKE(), AUTHTAG_ALLOW(), AUTHTAG_REMOTE(), and AUTHTAG_MASTER_KEY().
Returns:
0 if successful

-1 upon an error

auth_mod_t* auth_mod_alloc ( auth_scheme_t scheme,
tag_type_t  tag,
tag_value_t  value,
  ... 
)

Allocate an authentication module instance.

The function auth_mod_alloc() allocates an authentication module object.

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.

char const* auth_mod_name ( auth_mod_t am  ) 

Get authenticatin module name.

Since:
New in 1.12.4.

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

int auth_validate_digest_nonce ( auth_mod_t am,
auth_status_t as,
auth_response_t ar,
msg_time_t  now 
)

Validate nonce parameter.

Parameters:
am pointer to authentication module object
as authentication status structure [OUT]
ar decoded authentication response from client [IN]
now current time [IN]


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