1 siphttpdigest.h

     1 /*

     2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name        : siphttpdigest.h

    16 * Part of     : SIP Client

    17 * Interface   : SDK API, SIP Client API

    18 * Version     : 2.0

    19 *

    20 */

    21 

    22 

    23 

    24 #ifndef CSIPHTTPDIGEST_H

    25 #define CSIPHTTPDIGEST_H

    26 

    27 // INCLUDES 

    28 #include <e32base.h>

    29 #include "_sipcodecdefs.h"

    30 

    31 // FORWARD DECLARATIONS

    32 class CSIP;

    33 class MSIPHttpDigestChallengeObserver;

    34 class MSIPHttpDigestChallengeObserver2;

    35 class CSIPClientTransaction;

    36 class CSIPRefresh;

    37 

    38 // CLASS DECLARATION

    39 

    40 /**

    41 * @publishedAll

    42 * @released

    43 *

    44 * Class for managing SIP HTTP Digest security settings.

    45 * Class provides functions for setting/removing

    46 * HTTP Digest security mechanism related parameters.

    47 * If the user does not use the class for the providing credentials for the

    48 * received challenges, an error will be returned to the original request in

    49 * case it was challenged.

    50 * 

    51 * Note that the user will be asked to provide credentials one realm

    52 * at the time.

    53 *

    54 *  @lib sipclient.lib

    55 */

    56 class CSIPHttpDigest : public CBase

    57 	{

    58 	public: // Constructors and destructor

    59 	

    60 		/**

    61 		* Two-phased constructor.

    62 		* @param aSIP a handle to SIP server

    63 		* @param aObserver an observer for the received challenges

    64 		* @return New object, ownership is transferred.

    65 		*/

    66 		IMPORT_C static CSIPHttpDigest*

    67 			NewL(CSIP& aSIP,

    68 				 MSIPHttpDigestChallengeObserver& aObserver);

    69 				 

    70 		/**

    71 		* Two-phased constructor.

    72 		* @param aSIP a handle to SIP server

    73 		* @param aObserver an observer for the received challenges

    74 		* @return New object, ownership is transferred.

    75 		*/

    76 		IMPORT_C static CSIPHttpDigest*

    77 			NewLC(CSIP& aSIP,

    78 				  MSIPHttpDigestChallengeObserver& aObserver);

    79 

    80 		/**

    81 		* Two-phased constructor.

    82 		* @param aSIP a handle to SIP server

    83 		* @param aObserver2 an observer for the received challenges

    84 		* @return New object, ownership is transferred.

    85 		*/

    86 		IMPORT_C static CSIPHttpDigest*

    87 			NewL(CSIP& aSIP,

    88 				 MSIPHttpDigestChallengeObserver2& aObserver2);

    89 				 

    90 		/**

    91 		* Two-phased constructor.

    92 		* @param aSIP a handle to SIP server

    93 		* @param aObserver2 an observer for the received challenges

    94 		* @return New object, ownership is transferred.

    95 		*/

    96 		IMPORT_C static CSIPHttpDigest*

    97 			NewLC(CSIP& aSIP,

    98 				  MSIPHttpDigestChallengeObserver2& aObserver2);

    99 				  

   100 		IMPORT_C ~CSIPHttpDigest();

   101 

   102 	public: // New functions

   103 

   104         /**

   105 		* Sets credentials for the realm of the outbound proxy.

   106 		* Must be used in case the realm is the realm of the outbound proxy and

   107 		* the request for credentials was received from callback

   108 		* MSIPHttpDigestChallengeObserver::ChallengeReceived.		

   109 		* The user can set credentials only upon request from the

   110 		* SIP implementation.

   111 		* @pre aOutboundProxy, aRealm, aUsername and aPasswd must not be empty

   112 		*	   descriptors.

   113 		* @param aOutboundProxy an outbound proxy (FQDN or IP address)

   114 		* @param aRealm servers's realm

   115 		* @param aUsername user's name

   116 		* @param aPasswd user's password for the given server's realm

   117 		* @leave KErrNoMemory if out of memory

   118 		* @leave KErrArgument if some of the parameters is an empty descriptor

   119 		* @leave KErrSIPResourceNotAvailable if a required object has been

   120 		*		 deleted

   121 		*/

   122 		IMPORT_C void SetCredentialsL(const TDesC8& aOutboundProxy,

   123 			                          const TDesC8& aRealm,

   124 			                          const TDesC8& aUsername,

   125 			                          const TDesC8& aPasswd);

   126         /**

   127 		* Sets parameters for the realm.

   128 		* Should be used in case the realm is not a realm of an outbound proxy 

   129 		* and the request for credentials was received from callback

   130 		* MSIPHttpDigestChallengeObserver::ChallengeReceived.		

   131 		* The user can set credentials only upon request from the

   132 		* SIP implementation.

   133 		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.

   134 		* @param aRealm servers's realm

   135 		* @param aUsername user's name

   136 		* @param aPasswd user's password for the given server's realm

   137 		* @leave KErrNoMemory if out of memory

   138 		* @leave KErrArgument if some of the parameters is an empty descriptor

   139 		* @leave KErrSIPResourceNotAvailable if a required object has been

   140 		*		 deleted

   141 		*/

   142 		IMPORT_C void SetCredentialsL(const TDesC8& aRealm,

   143 			                          const TDesC8& aUsername,

   144 			                          const TDesC8& aPasswd);

   145 

   146         /**

   147 		* Sets credentials for the realm for the specific transaction.

   148 		* Must be used when the request for credentials was received 

   149 		* from callback MSIPHttpDigestChallengeObserver2::ChallengeReceived with 

   150 		* CSIPClientTransaction as the parameter.

   151 		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.

   152 		* @param aTransaction the transaction that was passed as a parameter

   153 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived

   154 		* @param aOutboundProxy an outbound proxy (FQDN or IP address) if

   155 		*        the challenge received had Proxy-Authenticate-header(s).

   156 		*        Otherwise KNullDesC8 should passed.

   157 		* @param aRealm servers's realm

   158 		* @param aUsername user's name

   159 		* @param aPasswd user's password for the given server's realm

   160 		* @leave KErrNoMemory if out of memory

   161 		* @leave KErrArgument if some of the parameters is an empty descriptor

   162 		* @leave KErrSIPResourceNotAvailable if a required object has been

   163 		*		 deleted

   164 		*/

   165 		IMPORT_C void SetCredentialsL(const CSIPClientTransaction& aTransaction,

   166 		                              const TDesC8& aOutboundProxy,

   167 			                          const TDesC8& aRealm,

   168 			                          const TDesC8& aUsername,

   169 			                          const TDesC8& aPasswd);

   170 

   171         /**

   172 		* Sets credentials for the realm for the specific refresh.

   173 		* Must be used when the request for credentials was received 

   174 		* from callback MSIPHttpDigestChallengeObserver2::ChallengeReceived with 

   175 		* CSIPRefresh as the parameter.

   176 		* @pre aRealm, aUsername and aPasswd must not be empty descriptors.

   177 		* @param aRefresh the refresh that was passed as a parameter

   178 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived

   179 		* @param aOutboundProxy an outbound proxy (FQDN or IP address) if

   180 		*        the challenge received had Proxy-Authenticate-header(s).

   181 		*        Otherwise KNullDesC8 should passed.

   182 		* @param aRealm servers's realm

   183 		* @param aUsername user's name

   184 		* @param aPasswd user's password for the given server's realm

   185 		* @leave KErrNoMemory if out of memory

   186 		* @leave KErrArgument if some of the parameters is an empty descriptor

   187 		* @leave KErrSIPResourceNotAvailable if a required object has been

   188 		*		 deleted

   189 		*/

   190 		IMPORT_C void SetCredentialsL(const CSIPRefresh& aRefresh,

   191 		                              const TDesC8& aOutboundProxy,

   192 			                          const TDesC8& aRealm,

   193 			                          const TDesC8& aUsername,

   194 			                          const TDesC8& aPasswd);

   195 			            

   196         /**

   197 		* Removes all set credentials for the realm.

   198 		* Must not be used if the user implements 

   199 		* MSIPHttpDigestChallengeObserver2.

   200 		* @pre aRealm must not be an empty descriptor

   201 		* @param aRealm servers's realm

   202 		* @return KErrNone if no error

   203 		*		  KErrArgument if aRealm is an empty descriptor

   204 		*		  KErrNoMemory if out of memory

   205 		*		  KErrNotFound if the given realm was not found

   206         */

   207 		IMPORT_C TInt RemoveCredentials(const TDesC8& aRealm);

   208 		

   209         /**

   210 		* Removes all set credentials by the user.

   211 		* Must not be used if the user implements 

   212 		* MSIPHttpDigestChallengeObserver2.		

   213 		* @return KErrNone if succesful; KErrNoMemory if out of memory 

   214         */

   215 		IMPORT_C TInt RemoveCredentials();

   216 					                                                        

   217 		/**

   218 		* Sets the observer	to listen for the possible received challenges. 

   219 		* Replaces the existing MSIPHttpDigestChallengeObserver or

   220 		* MSIPHttpDigestChallengeObserver2.

   221 		* @param aObserver an observer for the received challenges. 

   222 		*/

   223 		IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver& aObserver);

   224 		

   225 		/**

   226 		* Sets the observer	to listen for the possible received challenges. 

   227 		* Replaces the existing MSIPHttpDigestChallengeObserver or

   228 		* MSIPHttpDigestChallengeObserver2.

   229 		* @param aObserver an observer for the received challenges. 

   230 		*/

   231 		IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver2& aObserver);		

   232 		

   233 		/**

   234 		* Ignores the challenge for the realm. As a result the error will be

   235 		* generated to the original SIP request. 

   236 		* @pre aRealm must not be an empty descriptor

   237 		* @param aRealm a realm for which the challenge was ignored

   238 		* @return KErrNone if no error

   239 		*		  KErrNotFound if the given realm was not found

   240 		*		  KErrArgument if aRealm is an empty descriptor

   241 		*/

   242 		IMPORT_C TInt IgnoreChallenge(const TDesC8& aRealm);

   243 

   244 		/**

   245 		* Ignores the challenge for the realm for the specific transaction.

   246 		* As a result KErrForbidden will be generated 

   247 		* to the original SIP request.

   248 		* @pre aRealm must not be an empty descriptor

   249 		* @param aTransaction the transaction that was passed as a parameter

   250 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived		

   251 		* @param aRealm a realm for which the challenge was ignored

   252 		* @return KErrNone if no error

   253 		*		  KErrNotFound if the given realm was not found

   254 		*		  KErrArgument if aRealm is an empty descriptor

   255 		*/

   256 		IMPORT_C TInt IgnoreChallenge(const CSIPClientTransaction& aTransaction,

   257 		                              const TDesC8& aRealm);

   258 

   259 		/**

   260 		* Ignores the challenge for the realm for the specific refresh.

   261 		* As a result the error will be generated 

   262 		* to the original SIP request.

   263 		* @pre aRealm must not be an empty descriptor

   264 		* @param aRefresh the refresh that was passed as a parameter

   265 		*        to MSIPHttpDigestChallengeObserver2::ChallengeReceived		

   266 		* @param aRealm a realm for which the challenge was ignored

   267 		* @return KErrNone if no error

   268 		*		  KErrNotFound if the given realm was not found

   269 		*		  KErrArgument if aRealm is an empty descriptor

   270 		*/

   271 		IMPORT_C TInt IgnoreChallenge(const CSIPRefresh& aRefresh,

   272 		                              const TDesC8& aRealm);

   273 

   274 	public: // New functions, for internal use

   275 

   276 		void CSIPDeleted();

   277 

   278 	private: // Constructors

   279 

   280         CSIPHttpDigest(CSIP& aSIP);

   281 		CSIPHttpDigest(const CSIPHttpDigest& aHttpDigest);

   282 		CSIPHttpDigest& operator=(const CSIPHttpDigest& aHttpDigest);

   283 

   284 		void ConstructL(MSIPHttpDigestChallengeObserver& aObserver);

   285 		

   286 		void ConstructL(MSIPHttpDigestChallengeObserver2& aObserver2);

   287        

   288     private: // New functions

   289     

   290 		TInt RemoveCredentialParams(const TDesC8& aRealm) const;

   291 

   292 		void SetCredentialParamsL(TUint32 aRequestId,

   293 		                          TUint32 aRefreshId,

   294 		                          const TDesC8& aOutboundProxy,

   295 		                          const TDesC8& aRealm,

   296 				                  const TDesC8& aUsername,

   297 				                  const TDesC8& aPasswd) const;		

   298 		

   299 		TInt IgnoreChallenge(TUint32 aRequestId,

   300 		                     TUint32 aRefreshId,

   301 		                     const TDesC8& aRealm);       

   302           

   303     private: // Data

   304 

   305         CSIP* iSIP;

   306 

   307 	private: // For testing purposes

   308 

   309 	    UNIT_TEST(CSIP_Test)

   310 	};

   311 

   312 #endif // CSIPHTTPDIGEST_H