2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
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".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
15 * Name : siphttpdigest.h
16 * Part of : SIP Client
17 * Interface : SDK API, SIP Client API
24 #ifndef CSIPHTTPDIGEST_H
25 #define CSIPHTTPDIGEST_H
29 #include "_sipcodecdefs.h"
31 // FORWARD DECLARATIONS
33 class MSIPHttpDigestChallengeObserver;
34 class MSIPHttpDigestChallengeObserver2;
35 class CSIPClientTransaction;
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.
51 * Note that the user will be asked to provide credentials one realm
56 class CSIPHttpDigest : public CBase
58 public: // Constructors and destructor
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.
66 IMPORT_C static CSIPHttpDigest*
68 MSIPHttpDigestChallengeObserver& aObserver);
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.
76 IMPORT_C static CSIPHttpDigest*
78 MSIPHttpDigestChallengeObserver& aObserver);
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.
86 IMPORT_C static CSIPHttpDigest*
88 MSIPHttpDigestChallengeObserver2& aObserver2);
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.
96 IMPORT_C static CSIPHttpDigest*
98 MSIPHttpDigestChallengeObserver2& aObserver2);
100 IMPORT_C ~CSIPHttpDigest();
102 public: // New functions
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
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
122 IMPORT_C void SetCredentialsL(const TDesC8& aOutboundProxy,
123 const TDesC8& aRealm,
124 const TDesC8& aUsername,
125 const TDesC8& aPasswd);
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
142 IMPORT_C void SetCredentialsL(const TDesC8& aRealm,
143 const TDesC8& aUsername,
144 const TDesC8& aPasswd);
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
165 IMPORT_C void SetCredentialsL(const CSIPClientTransaction& aTransaction,
166 const TDesC8& aOutboundProxy,
167 const TDesC8& aRealm,
168 const TDesC8& aUsername,
169 const TDesC8& aPasswd);
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
190 IMPORT_C void SetCredentialsL(const CSIPRefresh& aRefresh,
191 const TDesC8& aOutboundProxy,
192 const TDesC8& aRealm,
193 const TDesC8& aUsername,
194 const TDesC8& aPasswd);
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
207 IMPORT_C TInt RemoveCredentials(const TDesC8& aRealm);
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
215 IMPORT_C TInt RemoveCredentials();
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.
223 IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver& aObserver);
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.
231 IMPORT_C void SetObserver(MSIPHttpDigestChallengeObserver2& aObserver);
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
242 IMPORT_C TInt IgnoreChallenge(const TDesC8& aRealm);
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
256 IMPORT_C TInt IgnoreChallenge(const CSIPClientTransaction& aTransaction,
257 const TDesC8& aRealm);
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
271 IMPORT_C TInt IgnoreChallenge(const CSIPRefresh& aRefresh,
272 const TDesC8& aRealm);
274 public: // New functions, for internal use
278 private: // Constructors
280 CSIPHttpDigest(CSIP& aSIP);
281 CSIPHttpDigest(const CSIPHttpDigest& aHttpDigest);
282 CSIPHttpDigest& operator=(const CSIPHttpDigest& aHttpDigest);
284 void ConstructL(MSIPHttpDigestChallengeObserver& aObserver);
286 void ConstructL(MSIPHttpDigestChallengeObserver2& aObserver2);
288 private: // New functions
290 TInt RemoveCredentialParams(const TDesC8& aRealm) const;
292 void SetCredentialParamsL(TUint32 aRequestId,
294 const TDesC8& aOutboundProxy,
295 const TDesC8& aRealm,
296 const TDesC8& aUsername,
297 const TDesC8& aPasswd) const;
299 TInt IgnoreChallenge(TUint32 aRequestId,
301 const TDesC8& aRealm);
307 private: // For testing purposes
312 #endif // CSIPHTTPDIGEST_H