1/*
2 * This file is part of the KDE libraries
3 * Copyright (C) 2000-2001 Dawit Alemayehu <adawit@kde.org>
4 *
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Library General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the License, or (at your option) any later version.
9 *
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Library General Public License for more details.
14 *
15 * You should have received a copy of the GNU Library General Public License
16 * along with this library; see the file COPYING.LIB. If not, write to
17 * the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19 */
20
21#ifndef KIO_AUTHINFO_H
22#define KIO_AUTHINFO_H
23
24#include "kio_export.h"
25
26#include <QtCore/QMap>
27#include <QtCore/QList>
28#include <QtCore/QStringList>
29#include <kurl.h>
30
31class QDBusArgument;
32
33namespace KIO {
34
35class AuthInfoPrivate;
36
37/**
38 * This class is intended to make it easier to prompt for, cache
39 * and retrieve authorization information.
40 *
41 * When using this class to cache, retrieve or prompt authentication
42 * information, you only need to set the necessary attributes. For
43 * example, to check whether a password is already cached, the only
44 * required information is the URL of the resource and optionally
45 * whether or not a path match should be performed. Similarly, to
46 * prompt for password you only need to optionally set the prompt,
47 * username (if already supplied), comment and commentLabel fields.
48 *
49 * <em>SPECIAL NOTE:</em> If you extend this class to add additional
50 * parameters do not forget to overload the stream insertion and
51 * extraction operators ("<<" and ">>") so that the added data can
52 * be correctly serialzed.
53 *
54 * @short A two way messaging class for passing authentication information.
55 * @author Dawit Alemayehu <adawit@kde.org>
56 */
57class KIO_EXPORT AuthInfo
58{
59 KIO_EXPORT friend QDataStream& operator<< (QDataStream& s, const AuthInfo& a);
60 KIO_EXPORT friend QDataStream& operator>> (QDataStream& s, AuthInfo& a);
61
62 KIO_EXPORT friend QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a);
63 KIO_EXPORT friend const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a);
64
65public:
66
67 /**
68 * Default constructor.
69 */
70 AuthInfo();
71
72 /**
73 * Copy constructor.
74 */
75 AuthInfo( const AuthInfo& info );
76
77 /**
78 * Destructor
79 * @since 4.1
80 */
81 ~AuthInfo();
82
83 /**
84 * Custom assignment operator.
85 */
86 AuthInfo& operator=( const AuthInfo& info );
87
88 /**
89 * Use this method to check if the object was modified.
90 * @return true if the object has been modified
91 */
92 bool isModified() const;
93
94 /**
95 * Use this method to indicate that this object has been modified.
96 * @param flag true to mark the object as modified, false to clear
97 */
98 void setModified( bool flag );
99
100 /**
101 * The URL for which authentication is to be stored.
102 *
103 * This field is required when attempting to cache authorization
104 * and retrieve it. However, it is not needed when prompting
105 * the user for authorization info.
106 *
107 * This setting is @em required except when prompting the
108 * user for password.
109 */
110 KUrl url;
111
112 /**
113 * This is @em required for caching.
114 */
115 QString username;
116
117 /**
118 * This is @em required for caching.
119 */
120 QString password;
121
122 /**
123 * Information to be displayed when prompting
124 * the user for authentication information.
125 *
126 * @note If this field is not set, the authentication
127 * dialog simply displays the preset default prompt.
128 *
129 * This setting is @em optional and empty by default.
130 */
131 QString prompt;
132
133 /**
134 * The text to displayed in the title bar of
135 * the password prompting dialog.
136 *
137 * @note If this field is not set, the authentication
138 * dialog simply displays the preset default caption.
139 *
140 * This setting is @em optional and empty by default.
141 */
142 QString caption;
143
144 /**
145 * Additional comment to be displayed when prompting
146 * the user for authentication information.
147 *
148 * This field allows you to display a short (no more than
149 * 80 characters) extra description in the password prompt
150 * dialog. For example, this field along with the
151 * commentLabel can be used to describe the server that
152 * requested the authentication:
153 *
154 * \code
155 * Server: Squid Proxy @ foo.com
156 * \endcode
157 *
158 * where "Server:" is the commentLabel and the rest is the
159 * actual comment. Note that it is always better to use
160 * the @p commentLabel field as it will be placed properly
161 * in the dialog rather than to include it within the actual
162 * comment.
163 *
164 * This setting is @em optional and empty by default.
165 */
166 QString comment;
167
168 /**
169 * Descriptive label to be displayed in front of the
170 * comment when prompting the user for password.
171 *
172 * This setting is @em optional and only applicable when
173 * the comment field is also set.
174 */
175 QString commentLabel;
176
177 /**
178 * A unique identifier that allows caching of multiple
179 * passwords for different resources in the same server.
180 *
181 * Mostly this setting is applicable to the HTTP protocol
182 * whose authentication scheme explicitly defines the use
183 * of such a unique key. However, any protocol that can
184 * generate or supply a unique id can effectively use it
185 * to distinguish passwords.
186 *
187 * This setting is @em optional and not set by default.
188 */
189 QString realmValue;
190
191 /**
192 * Field to store any extra authentication information for
193 * protocols that need it.
194 *
195 * This setting is @em optional and mostly applicable for HTTP
196 * protocol. However, any protocol can make use of it to
197 * store extra info.
198 */
199 QString digestInfo;
200
201 /**
202 * Flag that, if set, indicates whether a path match should be
203 * performed when requesting for cached authorization.
204 *
205 * A path is deemed to be a match if it is equal to or is a subset
206 * of the cached path. For example, if stored path is "/foo/bar"
207 * and the request's path set to "/foo/bar/acme", then it is a match
208 * whereas it would not if the request's path was set to "/foo".
209 *
210 * This setting is @em optional and false by default.
211 */
212 bool verifyPath;
213
214 /**
215 * Flag which if set forces the username field to be read-only.
216 *
217 * This setting is @em optional and false by default.
218 */
219 bool readOnly;
220
221 /**
222 * Flag to indicate the persistence of the given password.
223 *
224 * This is a two-way flag, when set before calling openPasswordDialog
225 * it makes the "keep Password" check box visible to the user.
226 * In return the flag will indicate the state of the check box.
227 * By default if the flag is checked the password will be cached
228 * for the entire life of the current KDE session otherwise the
229 * cached password is deleted right after the application using
230 * it has been closed.
231 */
232 bool keepPassword;
233
234 /**
235 * Flags for extra fields
236 * @since 4.1
237 */
238 enum FieldFlags
239 {
240 ExtraFieldNoFlags = 0,
241 ExtraFieldReadOnly = 1<<1,
242 ExtraFieldMandatory = 1<<2
243 };
244
245 /**
246 * Set Extra Field Value.
247 * Currently supported extra-fields:
248 * "domain" (QString),
249 * "anonymous" (bool)
250 * Setting it to an invalid QVariant() will disable the field.
251 * Extra Fields are disabled by default.
252 * @since 4.1
253 */
254 void setExtraField(const QString &fieldName, const QVariant & value);
255
256 /**
257 * Set Extra Field Flags
258 * @since 4.1
259 */
260 void setExtraFieldFlags(const QString &fieldName, const FieldFlags flags);
261
262 /**
263 * Get Extra Field Value
264 * Check QVariant::isValid() to find out if the field exists.
265 * @since 4.1
266 */
267 QVariant getExtraField(const QString &fieldName) const;
268
269 /**
270 * Get Extra Field Flags
271 * @since 4.1
272 */
273 AuthInfo::FieldFlags getExtraFieldFlags(const QString &fieldName) const;
274
275 /**
276 * Register the meta-types for AuthInfo. This is called from
277 * AuthInfo's constructor but needed by daemons on the DBus such
278 * as kpasswdserver.
279 * @since 4.3
280 */
281 static void registerMetaTypes();
282
283protected:
284 bool modified;
285
286private:
287 friend class ::KIO::AuthInfoPrivate;
288 AuthInfoPrivate * const d;
289};
290
291KIO_EXPORT QDataStream& operator<< (QDataStream& s, const AuthInfo& a);
292KIO_EXPORT QDataStream& operator>> (QDataStream& s, AuthInfo& a);
293
294KIO_EXPORT QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a);
295KIO_EXPORT const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a);
296
297/**
298 * A Singleton class that provides access to passwords
299 * stored in .netrc files for automatic login purposes.
300 * This is only meant to address backward compatibility
301 * with old automated ftp client style logins...
302 *
303 * @short An interface to the ftp .netrc files
304 * @author Dawit Alemayehu <adawit@kde.org>
305 */
306class KIO_EXPORT NetRC
307{
308public:
309
310 /**
311 * Specifies the mode to be used when searching for a
312 * matching automatic login info for a given site :
313 *
314 * @li exactOnly search entries with exact host name matches.
315 * @li defaultOnly search entries that are specified as "default".
316 * @li presetOnly search entries that are specified as "preset".
317 *
318 * @see lookup
319 */
320 enum LookUpModeFlag
321 {
322 exactOnly = 0x0002,
323 defaultOnly = 0x0004,
324 presetOnly = 0x0008
325 };
326 Q_DECLARE_FLAGS(LookUpMode, LookUpModeFlag)
327
328 /**
329 * Contains auto login information.
330 * @see lookup()
331 */
332 struct AutoLogin
333 {
334 QString type;
335 QString machine;
336 QString login;
337 QString password;
338 QMap<QString, QStringList> macdef;
339 };
340
341 /**
342 * A reference to the instance of the class.
343 * @return the class
344 */
345 static NetRC* self();
346
347 /**
348 * Looks up the @p login information for the given @p url.
349 *
350 * @param url the url whose login information will be checked
351 * @param login the login information will be writte here
352 * @param userealnetrc if true, use $HOME/.netrc fle
353 * @param type the type of the login. If null, the @p url's protocol
354 * will be taken
355 * @param mode the LookUpMode flags (ORed) for the query
356 */
357 bool lookup( const KUrl& url, AutoLogin& login,
358 bool userealnetrc = false,
359 const QString &type = QString(),
360 LookUpMode mode = LookUpMode(exactOnly) | defaultOnly );
361 /**
362 * Reloads the auto login information.
363 */
364 void reload();
365
366protected:
367 QString extract( const char*, const char*, int& );
368 int openf( const QString& );
369 bool parse( int );
370
371private:
372 NetRC();
373 ~NetRC();
374
375private:
376 static NetRC* instance;
377
378 class NetRCPrivate;
379 NetRCPrivate* const d;
380};
381}
382Q_DECLARE_OPERATORS_FOR_FLAGS(KIO::NetRC::LookUpMode)
383Q_DECLARE_METATYPE(KIO::AuthInfo)
384
385#endif
386