Sofia SIP User Agent Library - "iptsec" - Authentication Module

1.12.11

Module Meta Information

The iptsec module currently provides interfaces to HTTP Basic and Digest authentication, used by HTTP and SIP protocol elements. There are both client-side and server-side (authentication verification) functionality available.

Contact:

Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

Status:

Sofia SIP Core library

License:

LGPL

Server Verifying Authentication

The file <sofia-sip/auth_module.h> defines the interface used by a server verifying the authentication from client. After the server has created an authentication module, the usual authentication operation is simple enough:

1. server initializes an auth_status_t structure with information from the request
2. server calls auth_mod_method()
3. server checks the status from auth_status_t structure, sends an error response to the client if authentication fails
4. server proceeds serving the authenticated request.

If the operation is asynchronous, only a preliminary result is stored in the auth_status_t structure when the call to auth_mod_method() returns. In that case, the application can assign a callback function to the structure. The callback function is invoked when the authentication operation is completed. An asynchronous authentication operation can be terminated before its completion by calling auth_mod_cancel().

Server-Side Authentication Parameters

When the server creates the authentication module with auth_mod_create(), it can specify numerous parameters affecting the authentication protocol and algorithms. The parameter tags are defined in <sofia-sip/auth_module.h>. The most important parameters include:

• AUTHTAG_METHOD(),
• AUTHTAG_ALGORITHM(),
• AUTHTAG_QOP(), and
• AUTHTAG_REMOTE().

Client Authenticating User

The file <sofia-sip/auth_client.h> defines the interface used by a client authenticating a user with a server. Because there may be multiple servers or proxies requiring authentication, the client-side authentication information is represented using a list of auth_client_t objects. The client-side operation is as follows:

1. send a request
2. get a response with specific response code (401 or 407) and challenge
3. store the challenge to a list with auc_challenge()
4. prompt user and feed credentials (username and password) to the list with auc_credentials() or auc_all_credentials()
5. authorize a request (add credential headers to it) with auc_authorization() and resend the request

If there are several username/password pairs for multiple authentication realms required, the application must provide the corresponding realm as an argument to auc_all_credentials().