iptsec.docs 2.95 KB
Newer Older
Pekka Pessi's avatar
Pekka Pessi committed
1 2
/* -*- C -*- */

3
/**@MODULEPAGE "iptsec" - Authentication Module
Pekka Pessi's avatar
Pekka Pessi committed
4 5 6
 *
 * @section iptsec_meta Module Meta Information
 *
7
 * The iptsec module currently provides interfaces to HTTP
8 9 10 11
 * Basic and Digest authentication, used by HTTP and SIP protocol elements.
 * There are both
 * @ref auth_client "client-side" and
 * @ref auth_module "server-side"
Pekka Pessi's avatar
Pekka Pessi committed
12 13 14 15
 * (authentication verification) functionality available.
 *
 * @CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>
 *
16
 * @STATUS @SofiaSIP Core library
Pekka Pessi's avatar
Pekka Pessi committed
17 18 19 20 21
 *
 * @LICENSE LGPL
 *
 * @section auth_module Server Verifying Authentication
 *
22 23 24 25
 * 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
 * @ref auth_mod_t "authentication module", the usual authentication
 * operation is simple enough:
Pekka Pessi's avatar
Pekka Pessi committed
26 27
 * -# server initializes an #auth_status_t structure with information from
 *    the request
28 29
 * -# server calls auth_mod_method()
 * -# server checks the status from auth_status_t structure, sends an error
Pekka Pessi's avatar
Pekka Pessi committed
30 31 32 33
 *    response to the client if authentication fails
 * -# server proceeds serving the authenticated request.
 *
 * If the operation is asynchronous, only a preliminary result is stored in
34
 * the auth_status_t structure when the call to auth_mod_method() returns.
Pekka Pessi's avatar
Pekka Pessi committed
35 36 37 38 39 40 41 42 43
 * 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().
 *
 * @subsection auth_module_tags Server-Side Authentication Parameters
 *
 * When the server creates the authentication module with auth_mod_create(),
 * it can specify numerous parameters affecting the authentication protocol
44 45
 * and algorithms. The parameter tags are defined in
 * <sofia-sip/auth_module.h>. The most important parameters include:
Pekka Pessi's avatar
Pekka Pessi committed
46 47 48 49 50 51 52 53
 *
 * - AUTHTAG_METHOD(),
 * - AUTHTAG_ALGORITHM(),
 * - AUTHTAG_QOP(), and
 * - AUTHTAG_REMOTE().
 *
 * @section auth_client Client Authenticating User
 *
54
 * The file <sofia-sip/auth_client.h> defines the interface used by a client
Pekka Pessi's avatar
Pekka Pessi committed
55 56 57 58 59 60 61 62 63 64
 * 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:
 *
 * -# send a request
 * -# get a response with specific response code (401 or 407) and challenge
 * -# store the challenge to a list with auc_challenge()
 * -# prompt user and feed credentials (username and password) to the list
 *    with auc_credentials() or auc_all_credentials()
65
 * -# authorize a request (add credential headers to it) with
Pekka Pessi's avatar
Pekka Pessi committed
66 67 68 69 70 71
 *    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().
 */