1/*
2 This file is part of the KDE libraries
3 SPDX-FileCopyrightText: 2000-2001 Dawit Alemayehu <adawit@kde.org>
4
5 SPDX-License-Identifier: LGPL-2.0-or-later
6*/
7
8#ifndef KIO_AUTHINFO_H
9#define KIO_AUTHINFO_H
10
11#include "kiocore_export.h"
12
13#include <QList>
14#include <QMap>
15#include <QStringList>
16#include <QUrl>
17#include <QVariant> // Q_DECLARE_METATYPE
18
19#include <memory>
20
21class QDBusArgument;
22
23namespace KIO
24{
25class AuthInfoPrivate;
26
27/*!
28 * \class KIO::AuthInfo
29 * \inheaderfile KIO/AuthInfo
30 * \inmodule KIOCore
31 *
32 * \brief A two way messaging class for passing authentication information.
33 *
34 * This class is intended to make it easier to prompt for, cache
35 * and retrieve authorization information.
36 *
37 * When using this class to cache, retrieve or prompt authentication
38 * information, you only need to set the necessary attributes. For
39 * example, to check whether a password is already cached, the only
40 * required information is the URL of the resource and optionally
41 * whether or not a path match should be performed. Similarly, to
42 * prompt for password you only need to optionally set the prompt,
43 * username (if already supplied), comment and commentLabel fields.
44 *
45 * \note If you extend this class to add additional
46 * parameters do not forget to overload the stream insertion and
47 * extraction operators ("<<" and ">>") so that the added data can
48 * be correctly serialized.
49 *
50 */
51class KIOCORE_EXPORT AuthInfo
52{
53 /*!
54 *
55 */
56 KIOCORE_EXPORT friend QDataStream &operator<<(QDataStream &s, const AuthInfo &a);
57
58 /*!
59 *
60 */
61 KIOCORE_EXPORT friend QDataStream &operator>>(QDataStream &s, AuthInfo &a);
62
63 /*!
64 *
65 */
66 KIOCORE_EXPORT friend QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a);
67
68 /*!
69 *
70 */
71 KIOCORE_EXPORT friend const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a);
72
73public:
74 /*!
75 * Default constructor.
76 */
77 AuthInfo();
78
79 /*!
80 * Copy constructor.
81 */
82 AuthInfo(const AuthInfo &info);
83
84 ~AuthInfo();
85
86 AuthInfo &operator=(const AuthInfo &info);
87
88 /*!
89 * Use this method to check if the object was modified.
90 * Returns \c 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 *
97 * \a flag true to mark the object as modified, false to clear
98 */
99 void setModified(bool flag);
100
101 /*!
102 * The URL for which authentication is to be stored.
103 *
104 * This field is required when attempting to cache authorization
105 * and retrieve it. However, it is not needed when prompting
106 * the user for authorization info.
107 *
108 * This setting is \e required except when prompting the
109 * user for password.
110 */
111 QUrl url;
112
113 /*!
114 * This is \e required for caching.
115 */
116 QString username;
117
118 /*!
119 * This is \e required for caching.
120 */
121 QString password;
122
123 /*!
124 * Information to be displayed when prompting
125 * the user for authentication information.
126 *
127 * \note If this field is not set, the authentication
128 * dialog simply displays the preset default prompt.
129 *
130 * This setting is \e optional and empty by default.
131 */
132 QString prompt;
133
134 /*!
135 * The text to displayed in the title bar of
136 * the password prompting dialog.
137 *
138 * \note If this field is not set, the authentication
139 * dialog simply displays the preset default caption.
140 *
141 * This setting is \e optional and empty by default.
142 */
143 QString caption;
144
145 /*!
146 * Additional comment to be displayed when prompting
147 * the user for authentication information.
148 *
149 * This field allows you to display a short (no more than
150 * 80 characters) extra description in the password prompt
151 * dialog. For example, this field along with the
152 * commentLabel can be used to describe the server that
153 * requested the authentication:
154 *
155 * \code
156 * Server: Squid Proxy @ foo.com
157 * \endcode
158 *
159 * where "Server:" is the commentLabel and the rest is the
160 * actual comment. Note that it is always better to use
161 * the \a commentLabel field as it will be placed properly
162 * in the dialog rather than to include it within the actual
163 * comment.
164 *
165 * This setting is \e optional and empty by default.
166 */
167 QString comment;
168
169 /*!
170 * Descriptive label to be displayed in front of the
171 * comment when prompting the user for password.
172 *
173 * This setting is \e optional and only applicable when
174 * the comment field is also set.
175 */
176 QString commentLabel;
177
178 /*!
179 * A unique identifier that allows caching of multiple
180 * passwords for different resources in the same server.
181 *
182 * Mostly this setting is applicable to the HTTP protocol
183 * whose authentication scheme explicitly defines the use
184 * of such a unique key. However, any protocol that can
185 * generate or supply a unique id can effectively use it
186 * to distinguish passwords.
187 *
188 * This setting is \e optional and not set by default.
189 */
190 QString realmValue;
191
192 /*!
193 * Field to store any extra authentication information for
194 * protocols that need it.
195 *
196 * This setting is \e optional and mostly applicable for HTTP
197 * protocol. However, any protocol can make use of it to
198 * store extra info.
199 */
200 QString digestInfo;
201
202 /*!
203 * Flag that, if set, indicates whether a path match should be
204 * performed when requesting for cached authorization.
205 *
206 * A path is deemed to be a match if it is equal to or is a subset
207 * of the cached path. For example, if stored path is "/foo/bar"
208 * and the request's path set to "/foo/bar/acme", then it is a match
209 * whereas it would not if the request's path was set to "/foo".
210 *
211 * This setting is \e optional and false by default.
212 */
213 bool verifyPath;
214
215 /*!
216 * Flag which if set forces the username field to be read-only.
217 *
218 * This setting is \e optional and false by default.
219 */
220 bool readOnly;
221
222 /*!
223 * Flag to indicate the persistence of the given password.
224 *
225 * This is a two-way flag, when set before calling openPasswordDialog
226 * it makes the "keep Password" check box visible to the user.
227 * In return the flag will indicate the state of the check box.
228 * By default if the flag is checked the password will be cached
229 * for the entire life of the current KDE session otherwise the
230 * cached password is deleted right after the application using
231 * it has been closed.
232 */
233 bool keepPassword;
234
235 /*!
236 * Flags for extra fields
237 *
238 * \value ExtraFieldNoFlags
239 * \value ExtraFieldReadOnly
240 * \value ExtraFieldMandatory
241 */
242 enum FieldFlags {
243 ExtraFieldNoFlags = 0,
244 ExtraFieldReadOnly = 1 << 1,
245 ExtraFieldMandatory = 1 << 2,
246 };
247
248 /*!
249 * Set Extra Field Value.
250 * Currently supported extra-fields:
251 * "domain" (QString),
252 * "anonymous" (bool)
253 * Setting it to an invalid QVariant() will disable the field.
254 * Extra Fields are disabled by default.
255 */
256 void setExtraField(const QString &fieldName, const QVariant &value);
257
258 /*!
259 * Set Extra Field Flags
260 */
261 void setExtraFieldFlags(const QString &fieldName, const FieldFlags flags);
262
263 /*!
264 * Get Extra Field Value
265 * Check QVariant::isValid() to find out if the field exists.
266 */
267 QVariant getExtraField(const QString &fieldName) const;
268
269 /*!
270 * Get Extra Field Flags
271 */
272 AuthInfo::FieldFlags getExtraFieldFlags(const QString &fieldName) const;
273
274 /*!
275 * Register the meta-types for AuthInfo. This is called from
276 * AuthInfo's constructor but needed by daemons on the D-Bus such
277 * as kpasswdserver.
278 */
279 static void registerMetaTypes();
280
281protected:
282 bool modified;
283
284private:
285 friend class ::KIO::AuthInfoPrivate;
286 std::unique_ptr<AuthInfoPrivate> const d;
287};
288
289KIOCORE_EXPORT QDataStream &operator<<(QDataStream &s, const AuthInfo &a);
290KIOCORE_EXPORT QDataStream &operator>>(QDataStream &s, AuthInfo &a);
291
292KIOCORE_EXPORT QDBusArgument &operator<<(QDBusArgument &argument, const AuthInfo &a);
293KIOCORE_EXPORT const QDBusArgument &operator>>(const QDBusArgument &argument, AuthInfo &a);
294}
295
296Q_DECLARE_METATYPE(KIO::AuthInfo)
297
298#endif
299

source code of kio/src/core/authinfo.h