doc/Readme.uac_auth.txt
2c2d3561
 uac_auth Client / Server authentication 
1d8f98c5
 
 how to use uac_auth
 --------------------
 
 Requests with 407/401 replies are authenticated and resent by the 
 uac_auth SessionComponent plugin, if 
   1. Credentials are provided by the Session and 
   2. uac_auth is added as SessionEventHandler to the session 
     (so that the uac_auth gets incoming and outgoing messages).
 
 How to
 1) provide credentials
  * Derive your Session object from CredentialHolder:
 
e0736a63
   #include "AmUACAuth.h"
1d8f98c5
   ...
 
e0736a63
   class MyCall : public AmSession,
 	  	    public CredentialHolder
1d8f98c5
 
  * set credentials on session creation
 	AnnouncementDialog::AnnouncementDialog(...) 
     : CredentialHolder("myrealm", "myuser", "mypwd")
 
 
e0736a63
 2) enable uac_auth (add SessionEventHandler to session)
   MyCall* my_call=new MyCall();
   AmUACAuth::enable(my_call);
1d8f98c5
 
 see announce_auth app for example application
 
2c2d3561
 
 How to use server auth
 ----------------------
 
 To authenticate a request, use the "checkAuth" DI function.
 
  Arguments:
      args[0] - ArgObject pointing to the Request (AmSipRequest object)
      args[1] - realm
      args[2] - user
      args[3] - password
  Return values:
      ret[0] - code: 200 for successful auth, 401 for unsuccessful (ie.
      ret[1] - reason string
      ret[2] - optional auth header
 
 Limitations
 -----------
 
 - URI in auth hdr is not checked
 - multiple Authorization headers are probably not properly processed (only the first one is used)
 
 code example:
 
     AmDynInvokeFactory* fact = 
       AmPlugIn::instance()->getFactory4Di("uac_auth");
     if (NULL != fact) {
       AmDynInvoke* di_inst = fact->getInstance();
       if(di_inst) {
 	AmArg di_args, di_ret;
 	try {
 	  di_args.push(AmArg((AmObject*)&req));
 	  di_args.push("myrealm");
 	  di_args.push("myuser");
 	  di_args.push("mypwd");
 	  di_inst->invoke("checkAuth", di_args, di_ret);
 	  
 	  if (di_ret.size() >= 3) {
 	    if (di_ret[0].asInt() != 200) {
 	      DBG("Auth: replying %u %s - hdrs: '%s'\n",
 		  di_ret[0].asInt(), di_ret[1].asCStr(), di_ret[2].asCStr());
 	      dlg->reply(req, di_ret[0].asInt(), di_ret[1].asCStr(), NULL, di_ret[2].asCStr());
 	      return;
 	    } else {
 	      DBG("Successfully authenticated request.\n");
 	    }
 	  }
 	} catch (const AmDynInvoke::NotImplemented& ni) {
 	  ERROR("not implemented DI function 'checkAuth'\n");
 	} catch (const AmArg::OutOfBoundsException& oob) {
 	  ERROR("out of bounds in  DI call 'checkAuth'\n");
 	} catch (const AmArg::TypeMismatchException& oob) {
 	  ERROR("type mismatch  in  DI call checkAuth\n");
 	} catch (...) {
 	  ERROR("unexpected Exception  in  DI call checkAuth\n");
 	}
      }
   }