add sofia-sip 1.12.4 (plus some patches through 12/21/2006) to in tree libs

git-svn-id: http://svn.freeswitch.org/svn/freeswitch/trunk@3774 d0543943-73ff-0310-b7d9-9358b9ac24b2

libs/sofia-sip/libsofia-sip-ua/iptsec/iptsec.docs

@@ -0,0 +1,72 @@
+/* -*- C -*- */
+
+/**@MODULEPAGE "iptsec" - Authentication Module
+ *
+ * @section iptsec_meta 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 
+ * @ref auth_client "client-side" and 
+ * @ref auth_module "server-side" 
+ * (authentication verification) functionality available.
+ *
+ * @CONTACT Pekka Pessi <Pekka.Pessi@nokia.com>
+ *
+ * @STATUS @SofiaSIP Core library
+ *
+ * @LICENSE LGPL
+ *
+ * @section auth_module Server Verifying Authentication
+ *
+ * The file <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:
+
+ * -# server initializes an #auth_status_t structure with information from
+ *    the request
+ * -# server calls auth_mod_method() 
+ * -# server checks the status from auth_status_t structure, sends an error 
+ *    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
+ * 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().
+ *
+ * @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
+ * and algorithms. The parameter tags are defined in <auth_module.h>. The
+ * most important parameters include:
+ *
+ * - AUTHTAG_METHOD(),
+ * - AUTHTAG_ALGORITHM(),
+ * - AUTHTAG_QOP(), and
+ * - AUTHTAG_REMOTE().
+ *
+ * @section auth_client Client Authenticating User
+ *
+ * The file <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:
+ *
+ * -# 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()
+ * -# 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().
+ */