1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept xml:lang="en" id="GUID-83A4D862-368E-5DCC-998E-90144BE18A22"><title>How to Override Default Authentication Handling</title><prolog><metadata><keywords/></metadata></prolog><conbody><p>SIP provides a feature to the SIP client to handle authentication handling for services such as registration and session establishment. By default, this authentication challenge handling is handled by the SIP server using the digest mechanism. This mechanism is used by profile plug-ins that implement nondefault SIP behaviour which is also known as extensible Service Provider (xSP). </p> <p>These components are used when a SIP client handles authentication challenges independently. When an authentication problem is reported use <xref href="GUID-5ACD0BA9-66C7-31E8-844E-B39AE8691B2A.dita"><apiname>CSIPAuthorizationHeader</apiname></xref> and <xref href="GUID-3689FC15-B236-3B16-BAA5-70FF873DF3F1.dita"><apiname>CSIPProxyAuthorizationHeader</apiname></xref> objects to manipulate the registration or session initiation request headers. Then re-register a profile or reinitiate a session using the updated headers. </p> <p>To enable a client to override default authentication handling mechanisms, it must inform the SIP server by disabling the built-in security mechanism of the SIP using the <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita#GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B/GUID-FA3D6B89-4B41-3A56-85FB-06168D0B7B7B"><apiname>CSIP::SetSecurityHandlingL()</apiname></xref> function. The client uses <xref href="GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B.dita#GUID-AFB2603A-8A35-3E70-8EC2-229C9726F00B/GUID-0A3DB5AB-60D3-3756-B9DD-85F2B466E892"><apiname>CSIP::IsSecurityHandlingEnabled()</apiname></xref> function to determine what is handling the authentication challenges. This function returns <codeph>ETrue</codeph> if the built-in security mechanism of the SIP is used. </p> <p>When a SIP client handles authentication challenges independently, it uses <xref href="GUID-5ACD0BA9-66C7-31E8-844E-B39AE8691B2A.dita"><apiname>CSIPAuthorizationHeader</apiname></xref> and <xref href="GUID-3689FC15-B236-3B16-BAA5-70FF873DF3F1.dita"><apiname>CSIPProxyAuthorizationHeader</apiname></xref> objects to manipulate the registration or session initiation request headers when an authentication problem is reported. Re-registration of a profile or reinitiating a session is done using the updated headers. </p> <p>In the following illustration the client handles authentication challenges related to the profile registration. All authentication errors are then forwarded to the xSP profile agent plug-in. When an error is reported to the plug-in, it runs a proprietary authentication procedure and tries to re-register the profile. </p> <p>The following illustration shows the call flow of handling authentication challenges while registering a SIP profile: </p> <fig id="GUID-5A8E6082-8DD1-5465-AC32-8D34F45C11FF"><title>

    13           Call flow for handling 401 challenges using xSP profile agent plug-in 

    14         </title> <image href="GUID-FAC309FE-B7DA-572B-9165-BC9BEF944D83_d0e340852_href.png" placement="inline"/></fig> <p>In the following illustration the client handles authentication challenges related to the session initiation. All the authentication errors are then forwarded to the xSP provider. When an error is reported to the provider, it runs a proprietary authentication procedure and tries to reinitiate the session. </p> <p>The following illustration shows the call flow of handling authentication challenges while establishing a session: </p> <fig id="GUID-03AEF001-D35A-5DA8-842D-5B20451F16ED"><title>

    15           Call flow for handling 401 challenges using xSP provider 

    16         </title> <image href="GUID-FC230C68-18FC-5DB9-A5B2-942B48DC5590_d0e340864_href.png" placement="inline"/></fig> <section><title>See also</title> <p> <xref href="GUID-B0EF8500-0A49-5EA8-B7FF-8149E5F03693.dita">How to use the SIP Client API</xref>  </p> </section> </conbody></concept>