KWallet

kwallet.h
1 /*
2  This file is part of the KDE project
3 
4  SPDX-FileCopyrightText: 2002-2004 George Staikos <[email protected]>
5 
6  SPDX-License-Identifier: LGPL-2.0-or-later
7 */
8 
9 #ifndef _KWALLET_H
10 #define _KWALLET_H
11 
12 #include <QObject>
13 #include <QStringList>
14 #include <qwindowdefs.h> // krazy:exclude=includes (for WId)
15 
16 #include <kwallet_export.h>
17 
18 /**
19  * NOTE: KSecretsService folder semantics
20  * The KWallet API uses folders for organising items. KSecretsService does not
21  * have this notion. But it uses attributes that can be applied arbitrarily on
22  * all the items. The KWallet code that maps to KSecretsService applies an special
23  * attribute KSS_ATTR_ENTRYFOLDER to all items with the currentFolder() value.
24  * The KWallet folder API's calls will always succeed and they'll only change the
25  * current folder value. The folderList() call will scan all the collection
26  * items and collect the KSS_ATTR_ENTRYFOLDER attributes into a list.
27  */
28 
29 /**
30  * NOTE: KWalet API distinguish KSecretsService collection items by attaching
31  * them some specific attributes, defined below
32  */
33 #define KSS_ATTR_ENTRYFOLDER "kwallet.folderName"
34 #define KSS_ATTR_WALLETTYPE "kwallet.type"
35 
36 namespace KWallet
37 {
38 /**
39  * KDE Wallet
40  *
41  * This class implements a generic system-wide Wallet for KDE. This is the
42  * ONLY public interface.
43  *
44  * @author George Staikos <[email protected]>
45  * @short KDE Wallet Class
46  */
47 class KWALLET_EXPORT Wallet : public QObject
48 {
49  Q_OBJECT
50 protected:
51  /**
52  * Construct a KWallet object.
53  * @internal
54  * @param handle The handle for the wallet.
55  * @param name The name of the wallet.
56  */
57  Wallet(int handle, const QString &name);
58  /**
59  * Copy a KWallet object.
60  * @internal
61  */
62  Wallet(const Wallet &);
63 
64 public:
65  enum EntryType {
66  Unknown = 0,
67  Password,
68  Stream,
69  Map,
70  Unused = 0xffff,
71  };
72 
73  /**
74  * Destroy a KWallet object. Closes the wallet.
75  */
76  ~Wallet() override;
77 
78  /**
79  * List all the wallets available.
80  * @return Returns a list of the names of all wallets that are
81  * open.
82  */
83  static QStringList walletList();
84 
85  /**
86  * Determine if the KDE wallet is enabled. Normally you do
87  * not need to use this because openWallet() will just fail.
88  * @return Returns true if the wallet enabled, else false.
89  */
90  static bool isEnabled();
91 
92  /**
93  * Determine if the wallet @p name is open by any application.
94  * @param name The name of the wallet to check.
95  * @return Returns true if the wallet is open, else false.
96  */
97  static bool isOpen(const QString &name);
98 
99  /**
100  * Close the wallet @p name. The wallet will only be closed
101  * if it is open but not in use (rare), or if it is forced
102  * closed.
103  * @param name The name of the wallet to close.
104  * @param force Set true to force the wallet closed even if it
105  * is in use by others.
106  * @return Returns 0 on success, non-zero on error.
107  */
108  static int closeWallet(const QString &name, bool force);
109 
110  /**
111  * Delete the wallet @p name. The wallet will be forced closed
112  * first.
113  * @param name The name of the wallet to delete.
114  * @return Returns 0 on success, non-zero on error.
115  */
116  static int deleteWallet(const QString &name);
117 
118  /**
119  * Disconnect the application @p app from @p wallet.
120  * @param wallet The name of the wallet to disconnect.
121  * @param app The name of the application to disconnect.
122  * @return Returns true on success, false on error.
123  */
124  static bool disconnectApplication(const QString &wallet, const QString &app);
125 
126  enum OpenType {
127  Synchronous = 0,
128  Asynchronous,
129  Path,
130  OpenTypeUnused = 0xff,
131  };
132 
133  /**
134  * Open the wallet @p name. The user will be prompted to
135  * allow your application to open the wallet, and may be
136  * prompted for a password. You are responsible for deleting
137  * this object when you are done with it.
138  * @param name The name of the wallet to open.
139  * @param ot If Asynchronous, the call will return
140  * immediately with a non-null pointer to an
141  * invalid wallet. You must immediately connect
142  * the walletOpened() signal to a slot so that
143  * you will know when it is opened, or when it
144  * fails.
145  * @param w The window id to associate any dialogs with. You can pass
146  * 0 if you don't have a window the password dialog should
147  * associate with.
148  * @return Returns a pointer to the wallet if successful,
149  * or a null pointer on error or if rejected.
150  * A null pointer can also be returned if user choose to
151  * deactivate the wallet system.
152  */
153  static Wallet *openWallet(const QString &name, WId w, OpenType ot = Synchronous);
154 
155  /**
156  * List the applications that are using the wallet @p wallet.
157  * @param wallet The wallet to query.
158  * @return Returns a list of all DCOP application IDs using
159  * the wallet.
160  */
161  static QStringList users(const QString &wallet);
162 
163  /**
164  * The name of the wallet used to store local passwords.
165  */
166  static const QString LocalWallet();
167 
168  /**
169  * The name of the wallet used to store network passwords.
170  */
171  static const QString NetworkWallet();
172 
173  /**
174  * The standardized name of the password folder.
175  * It is automatically created when a wallet is created, but
176  * the user may still delete it so you should check for its
177  * existence and recreate it if necessary and desired.
178  */
179  static const QString PasswordFolder();
180 
181  /**
182  * The standardized name of the form data folder.
183  * It is automatically created when a wallet is created, but
184  * the user may still delete it so you should check for its
185  * existence and recreate it if necessary and desired.
186  */
187  static const QString FormDataFolder();
188 
189  /**
190  * Request to the wallet service to change the password of
191  * the wallet @p name.
192  * @param name The wallet to change the password of.
193  * @param w The window id to associate any dialogs with. You can pass
194  * 0 if you don't have a window the password dialog should
195  * associate with.
196  */
197  static void changePassword(const QString &name, WId w);
198 
199  /**
200  * This syncs the wallet file on disk with what is in memory.
201  * You don't normally need to use this. It happens
202  * automatically on close.
203  * @return Returns 0 on success, non-zero on error.
204  */
205  virtual int sync();
206 
207  /**
208  * This closes and locks the current wallet. It will
209  * disconnect all applications using the wallet.
210  * @return Returns 0 on success, non-zero on error.
211  */
212  virtual int lockWallet();
213 
214  /**
215  * The name of the current wallet.
216  */
217  virtual const QString &walletName() const;
218 
219  /**
220  * Determine if the current wallet is open, and is a valid
221  * wallet handle.
222  * @return Returns true if the wallet handle is valid and open.
223  */
224  virtual bool isOpen() const;
225 
226  /**
227  * Request to the wallet service to change the password of
228  * the current wallet.
229  * @param w The window id to associate any dialogs with. You can pass
230  * 0 if you don't have a window the password dialog should
231  * associate with.
232  */
233  virtual void requestChangePassword(WId w);
234 
235  /**
236  * Obtain the list of all folders contained in the wallet.
237  * @return Returns an empty list if the wallet is not open.
238  */
239  virtual QStringList folderList();
240 
241  /**
242  * Determine if the folder @p f exists in the wallet.
243  * @param f the name of the folder to check for
244  * @return Returns true if the folder exists in the wallet.
245  */
246  virtual bool hasFolder(const QString &f);
247 
248  /**
249  * Set the current working folder to @p f. The folder must
250  * exist, or this call will fail. Create a folder with
251  * createFolder().
252  * @param f the name of the folder to make the working folder
253  * @return Returns true if the folder was successfully set.
254  */
255  virtual bool setFolder(const QString &f);
256 
257  /**
258  * Remove the folder @p f and all its entries from the wallet.
259  * @param f the name of the folder to remove
260  * @return Returns true if the folder was successfully removed.
261  */
262  virtual bool removeFolder(const QString &f);
263 
264  /**
265  * Created the folder @p f.
266  * @param f the name of the folder to create
267  * @return Returns true if the folder was successfully created.
268  */
269  virtual bool createFolder(const QString &f);
270 
271  /**
272  * Determine the current working folder in the wallet.
273  * If the folder name is empty, it is working in the global
274  * folder, which is valid but discouraged.
275  * @return Returns the current working folder.
276  */
277  virtual const QString &currentFolder() const;
278 
279  /**
280  * Return the list of keys of all entries in this folder.
281  * @return Returns an empty list if the wallet is not open, or
282  * if the folder is empty.
283  */
284  virtual QStringList entryList();
285 
286  // TODO KDE5: a entryList(folder) so that kwalletmanager can list a folder without
287  // having to call setFolder before and after (which calls contains() in each)
288 
289  /**
290  * Rename the entry @p oldName to @p newName.
291  * @param oldName The original key of the entry.
292  * @param newName The new key of the entry.
293  * @return Returns 0 on success, non-zero on error.
294  */
295  virtual int renameEntry(const QString &oldName, const QString &newName);
296 
297  /**
298  * Read the entry @p key from the current folder.
299  * The entry format is unknown except that it is either a
300  * QByteArray or a QDataStream, which effectively means that
301  * it is anything.
302  * @param key The key of the entry to read.
303  * @param value A buffer to fill with the value.
304  * @return Returns 0 on success, non-zero on error.
305  */
306  virtual int readEntry(const QString &key, QByteArray &value);
307 
308  /**
309  * Read the map entry @p key from the current folder.
310  * @param key The key of the entry to read.
311  * @param value A map buffer to fill with the value.
312  * @return Returns 0 on success, non-zero on error. Will
313  * return an error if the key was not originally
314  * written as a map.
315  */
316  virtual int readMap(const QString &key, QMap<QString, QString> &value);
317 
318  /**
319  * Read the password entry @p key from the current folder.
320  * @param key The key of the entry to read.
321  * @param value A password buffer to fill with the value.
322  * @return Returns 0 on success, non-zero on error. Will
323  * return an error if the key was not originally
324  * written as a password.
325  */
326  virtual int readPassword(const QString &key, QString &value);
327 
328 #if KWALLET_ENABLE_DEPRECATED_SINCE(5, 72)
329  /**
330  * Read the entries matching @p key from the current folder.
331  * The entry format is unknown except that it is either a
332  * QByteArray or a QDataStream, which effectively means that
333  * it is anything.
334  * @param key The key of the entry to read. Wildcards
335  * are supported.
336  * @param value A buffer to fill with the value. The key in
337  * the map is the entry key.
338  * @return Returns 0 on success, non-zero on error.
339  *
340  * @deprecated Since 5.72, use entriesList(bool *)
341  */
342  KWALLET_DEPRECATED_VERSION(5, 72, "Use entriesList(bool *)")
343  int readEntryList(const QString &key, QMap<QString, QByteArray> &value);
344 #endif
345 
346 #if KWALLET_ENABLE_DEPRECATED_SINCE(5, 72)
347  /**
348  * Read the map entry @p key from the current folder.
349  * @param key The key of the entry to read. Wildcards
350  * are supported.
351  * @param value A buffer to fill with the value. The key in
352  * the map is the entry key.
353  * @return Returns 0 on success, non-zero on error. Will
354  * return an error if the key was not originally
355  * written as a map.
356  *
357  * @deprecated Since 5.72, use mapList(bool *)
358  */
359  KWALLET_DEPRECATED_VERSION(5, 72, "Use mapList(bool *)")
360  int readMapList(const QString &key, QMap<QString, QMap<QString, QString>> &value);
361 #endif
362 
363 #if KWALLET_ENABLE_DEPRECATED_SINCE(5, 72)
364  /**
365  * Read the password entry @p key from the current folder.
366  * @param key The key of the entry to read. Wildcards
367  * are supported.
368  * @param value A buffer to fill with the value. The key in
369  * the map is the entry key.
370  * @return Returns 0 on success, non-zero on error. Will
371  * return an error if the key was not originally
372  * written as a password.
373  *
374  * @deprecated Since 5.72, use passwordList(bool *)
375  */
376  KWALLET_DEPRECATED_VERSION(5, 72, "Use passwordList(bool *)")
377  int readPasswordList(const QString &key, QMap<QString, QString> &value);
378 #endif
379 
380  /**
381  * Get a list of all the entries in the current folder. The entry
382  * format is unknown except that it is either a QByteArray or a
383  * QDataStream, which effectively means that it could be anything.
384  *
385  * @param ok if not nullptr, the object this parameter points to will be set
386  * to true to indicate success or false otherwise
387  * @return a map of key/value pairs where the key in the map is the entry key
388  *
389  * @since 5.72
390  */
391  QMap<QString, QByteArray> entriesList(bool *ok) const;
392 
393  /**
394  * Get a list of all the maps in the current folder.
395  *
396  * @param ok if not nullptr, the object this parameter points to will be set
397  * to true to indicate success or false otherwise. Note that if any
398  * of the keys was not originally written as a map, the object will
399  * be set to false
400  *
401  * @return a map of key/value pairs where the key in the map is the entry key
402  *
403  * @since 5.72
404  */
405  QMap<QString, QMap<QString, QString>> mapList(bool *ok) const;
406 
407  /**
408  * Get a list of all the passwords in the current folder, which can
409  * be used to populate a list view in a password manager.
410  *
411  * @param ok if not nullptr, the object this parameter points to will be
412  * set to true to indicate success or false otherwise. Note that
413  * the object will be set to false if any of the keys was not
414  * originally written as a password
415  *
416  * @return a map of key/value pairs, where the key in the map is the entry key
417  *
418  * @since 5.72
419  */
420  QMap<QString, QString> passwordList(bool *ok) const;
421 
422  /**
423  * Write @p key = @p value as a binary entry to the current
424  * folder. Be careful with this, it could cause inconsistency
425  * in the future since you can put an arbitrary entry type in
426  * place.
427  * @param key The key of the new entry.
428  * @param value The value of the entry.
429  * @param entryType The type of the entry.
430  * @return Returns 0 on success, non-zero on error.
431  */
432  virtual int writeEntry(const QString &key, const QByteArray &value, EntryType entryType);
433 
434  /**
435  * Write @p key = @p value as a binary entry to the current
436  * folder.
437  * @param key The key of the new entry.
438  * @param value The value of the entry.
439  * @return Returns 0 on success, non-zero on error.
440  */
441  virtual int writeEntry(const QString &key, const QByteArray &value);
442 
443  /**
444  * Write @p key = @p value as a map to the current folder.
445  * @param key The key of the new entry.
446  * @param value The value of the map.
447  * @return Returns 0 on success, non-zero on error.
448  */
449  virtual int writeMap(const QString &key, const QMap<QString, QString> &value);
450 
451  /**
452  * Write @p key = @p value as a password to the current folder.
453  * @param key The key of the new entry.
454  * @param value The value of the password.
455  * @return Returns 0 on success, non-zero on error.
456  */
457  virtual int writePassword(const QString &key, const QString &value);
458 
459  /**
460  * Determine if the current folder has they entry @p key.
461  * @param key The key to search for.
462  * @return Returns true if the folder contains @p key.
463  */
464  virtual bool hasEntry(const QString &key);
465 
466  /**
467  * Remove the entry @p key from the current folder.
468  * @param key The key to remove.
469  * @return Returns 0 on success, non-zero on error.
470  */
471  virtual int removeEntry(const QString &key);
472 
473  /**
474  * Determine the type of the entry @p key in this folder.
475  * @param key The key to look up.
476  * @return Returns an enumerated type representing the type
477  * of the entry.
478  */
479  virtual EntryType entryType(const QString &key);
480 
481  /**
482  * Determine if a folder does not exist in a wallet. This
483  * does not require decryption of the wallet.
484  * This is a handy optimization to avoid prompting the user
485  * if your data is certainly not in the wallet.
486  * @param wallet The wallet to look in.
487  * @param folder The folder to look up.
488  * @return Returns true if the folder does NOT exist in the
489  * wallet, or the wallet does not exist.
490  */
491  static bool folderDoesNotExist(const QString &wallet, const QString &folder);
492 
493  /**
494  * Determine if an entry in a folder does not exist in a
495  * wallet. This does not require decryption of the wallet.
496  * This is a handy optimization to avoid prompting the user
497  * if your data is certainly not in the wallet.
498  * @param wallet The wallet to look in.
499  * @param folder The folder to look in.
500  * @param key The key to look up.
501  * @return Returns true if the key does NOT exist in the
502  * wallet, or the folder or wallet does not exist.
503  */
504  static bool keyDoesNotExist(const QString &wallet, const QString &folder, const QString &key);
505 
506  /**
507  * Determine if the KWallet API is using the KSecretsService infrastructure
508  * This can ben changed in system settings
509  * @return Returns true if the KSecretsService infrastructure is active
510  */
511  static bool isUsingKSecretsService();
512 
513 Q_SIGNALS:
514  /**
515  * Emitted when this wallet is closed.
516  */
517  void walletClosed();
518 
519  /**
520  * Emitted when a folder in this wallet is updated.
521  * @param folder The folder that was updated.
522  */
523  void folderUpdated(const QString &folder);
524 
525  /**
526  * Emitted when the folder list is changed in this wallet.
527  */
528  void folderListUpdated();
529 
530  /**
531  * Emitted when a folder in this wallet is removed.
532  * @param folder The folder that was removed.
533  */
534  void folderRemoved(const QString &folder);
535 
536  /**
537  * Emitted when a wallet is opened in asynchronous mode.
538  * @param success True if the wallet was opened successfully.
539  */
540  void walletOpened(bool success);
541 
542 private Q_SLOTS:
543  /**
544  * @internal
545  * D-Bus slot for signals emitted by the wallet service.
546  */
547  void slotWalletClosed(int handle);
548 
549  /**
550  * @internal
551  * D-Bus slot for signals emitted by the wallet service.
552  */
553  void slotFolderUpdated(const QString &wallet, const QString &folder);
554 
555  /**
556  * @internal
557  * D-Bus slot for signals emitted by the wallet service.
558  */
559  void slotFolderListUpdated(const QString &wallet);
560 
561  /**
562  * @internal
563  * D-Bus slot for signals emitted by the wallet service.
564  */
565  void slotApplicationDisconnected(const QString &wallet, const QString &application);
566 
567  /**
568  * @internal
569  * Callback for kwalletd
570  * @param tId identifier for the open transaction
571  * @param handle the wallet's handle
572  */
573  void walletAsyncOpened(int tId, int handle);
574 
575  /**
576  * @internal
577  * D-Bus error slot.
578  */
579  void emitWalletAsyncOpenError();
580 
581  /**
582  * @internal
583  * Emits wallet opening success.
584  */
585  void emitWalletOpened();
586 
587  /**
588  * @internal
589  * Receives status changed notifications from KSecretsService infrastructure
590  */
591  void slotCollectionStatusChanged(int);
592  /**
593  * @internal
594  * Received delete notification from KSecretsService infrastructure
595  */
596  void slotCollectionDeleted();
597 
598 private:
599  class WalletPrivate;
600  WalletPrivate *const d;
601  Q_PRIVATE_SLOT(d, void walletServiceUnregistered())
602 
603 protected:
604  /**
605  * @internal
606  */
607  virtual void virtual_hook(int id, void *data);
608 };
609 
610 }
611 
612 #endif //_KWALLET_H
KDE Wallet.
Definition: kwallet.h:47
const QLatin1String name
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jan 22 2022 22:53:25 by doxygen 1.8.11 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.