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

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