PolkitQt-1

polkitqt1-authority.h
1 /*
2  This file is part of the Polkit-qt project
3  SPDX-FileCopyrightText: 2009 Daniel Nicoletti <[email protected]>
4  SPDX-FileCopyrightText: 2009 Dario Freddi <[email protected]>
5  SPDX-FileCopyrightText: 2009 Jaroslav Reznik <[email protected]>
6  SPDX-FileCopyrightText: 2009 Radek Novacek <[email protected]>
7 
8  SPDX-License-Identifier: LGPL-2.0-or-later
9 */
10 
11 #ifndef POLKITQT1_AUTHORITY_H
12 #define POLKITQT1_AUTHORITY_H
13 
14 #include "polkitqt1-core-export.h"
15 #include "polkitqt1-identity.h"
16 #include "polkitqt1-subject.h"
17 #include "polkitqt1-temporaryauthorization.h"
18 #include "polkitqt1-actiondescription.h"
19 
20 #include <QObject>
21 #include <QMetaType>
22 #include <QStringList>
23 
24 typedef struct _PolkitAuthority PolkitAuthority;
25 
26 /**
27  * \namespace PolkitQt1 PolkitQt
28  *
29  * \brief Namespace wrapping Polkit-Qt classes
30  *
31  * This namespace wraps all Polkit-Qt classes.
32  */
33 namespace PolkitQt1
34 {
35 
36 typedef QMap<QString, QString> DetailsMap;
37 
38 /**
39  * \class Authority polkitqt1-authority.h Authority
40  * \author Daniel Nicoletti <[email protected]>
41  * \author Dario Freddi <[email protected]>
42  * \author Jaroslav Reznik <[email protected]>
43  *
44  * \brief Convenience class for Qt/KDE applications
45  *
46  * This class is a singleton that provides makes easy the usage
47  * of PolKitAuthority. It emits configChanged()
48  * whenever PolicyKit files change (e.g. the PolicyKit.conf
49  * or .policy files) or when ConsoleKit reports activities changes.
50  *
51  * \note This class is a singleton, its constructor is private.
52  * Call Authority::instance() to get an instance of the Authority object.
53  * Do not delete Authority::instance(), cleanup will be done automatically.
54  */
55 class POLKITQT1_CORE_EXPORT Authority : public QObject
56 {
57  Q_OBJECT
58  Q_DISABLE_COPY(Authority)
59 public:
60  enum Result {
61  /** Result unknown */
62  Unknown = 0x00,
63  /** The subject is authorized for the specified action */
64  Yes = 0x01,
65  /** The subject is not authorized for the specified action */
66  No = 0x02,
67  /** The subject is authorized if more information is provided */
68  Challenge = 0x03
69  };
70  Q_ENUM(Result)
71 
73  /** No flags set **/
74  None = 0x00,
75  /** If the subject can obtain the authorization through authentication,
76  * and an authentication agent is available, then attempt to do so.
77  *
78  * Note, this means that the method used for checking authorization is likely
79  * to block for a long time. **/
80  AllowUserInteraction = 0x01
81  };
82  Q_DECLARE_FLAGS(AuthorizationFlags, AuthorizationFlag)
83 
84  /** Error codes for the authority class */
85  enum ErrorCode {
86  /** No error occurred **/
87  E_None = 0x00,
88  /** Authority cannot be obtained **/
89  E_GetAuthority = 0x01,
90  /** Authority check failed **/
91  E_CheckFailed = 0x02,
92  /** Wrong or empty subject was given **/
93  E_WrongSubject = 0x03,
94  /** Action returned unknown result **/
95  E_UnknownResult = 0x04,
96  /** Enumerating actions failed **/
97  E_EnumFailed = 0x05,
98  /** Registration of authentication agent failed **/
99  E_RegisterFailed = 0x06,
100  /** Unregistration of authentication agent failed **/
101  E_UnregisterFailed = 0x07,
102  /** Cookie or polkitqt1-identity.handled to the action is empty **/
103  E_CookieOrIdentityEmpty = 0x08,
104  /** Response of auth agent failed **/
105  E_AgentResponseFailed = 0x09,
106  /** Revoke temporary authorizations failed **/
107  E_RevokeFailed = 0x0A
108  };
109  Q_ENUM(ErrorCode)
110 
111  /**
112  * \brief Returns the instance of Authority
113  *
114  * Returns the current instance of Authority. Call this function whenever
115  * you need to access the Authority class.
116  *
117  * \note Authority is a singleton. Memory is handled by polkit-qt, so you just
118  * need to call this function to get a working instance of Authority.
119  * Don't delete the object after having used it.
120  *
121  * \param authority use this if you want to set an explicit PolkitAuthority. If you
122  * don't know what this implies, simply ignore the parameter. In case
123  * you want to use it, be sure of streaming it the first time you call
124  * this function, otherwise it will have no effect.
125  *
126  * \return The current authority instance
127  */
128  static Authority *instance(PolkitAuthority *authority = nullptr);
129 
130  ~Authority() override;
131 
132  /**
133  * You should always call this method after every action. No action will be allowed
134  * if the object is in error state. Use clearError() to clear the error message.
135  *
136  * \see lastError
137  * \see clearError
138  *
139  * \return \c true if an error occurred, \c false if the library is ready
140  */
141  bool hasError() const;
142 
143  /**
144  * \return the code of last error
145  */
146  ErrorCode lastError() const;
147 
148  /**
149  * Get detail information about error that occurred.
150  *
151  * \return detail message
152  */
153  const QString errorDetails() const;
154 
155  /**
156  * Use this method to clear the error message.
157  */
158  void clearError();
159 
160  /**
161  * Returns the current instance of PolkitAuthority. If you are handling
162  * it through Polkit-qt (which is quite likely, since you are calling
163  * this function), DO NOT use any PolicyKit API's specific method that
164  * modifies the instance on it, unless you're completely aware of what you're doing and
165  * of the possible consequencies. Use this instance only to gather information.
166  *
167  * \return the current PolkitAuthority instance
168  */
169  PolkitAuthority *polkitAuthority() const;
170 
171  /**
172  * This function should be used by mechanisms (e.g.: helper applications).
173  * It returns the action should be carried out, so if the caller was
174  * actually authorized to perform it. The result is in form of a Result, so that
175  * you can have more control over the whole process, and detect an eventual error.
176  * Most of the times you simply want to check if the result is == to \c Result::Yes,
177  * if you don't have specific needs.
178  *
179  * It is CRITICAL that you call this function
180  * and check what it returns before doing anything in your helper, since otherwise
181  * you could be actually performing an action from an unknown or unauthorized caller.
182  *
183  * When operation is finished, signal checkAuthorizationFinish is emitted
184  * with result of authorization check in its parameter.
185  *
186  * \see checkAuthorizationSync Synchronous version of this method.
187  * \see checkAuthorizationFinished Signal that is emitted when this method finishes.
188  * \see checkAuthorizationCancel Use it to cancel execution of this method.
189  *
190  * \param actionId the Id of the action in question
191  * \param subject subject that the action is authorized for (e.g. unix process)
192  * \param flags flags that influences the authorization checking
193  */
194  void checkAuthorization(const QString &actionId, const Subject &subject,
195  AuthorizationFlags flags);
196 
197  /**
198  * This function does the same as checkAuthorization(const QString&, const
199  * Subject&, AuthorizationFlags), but also accepts a
200  * DetailsMap parameter. This map can contain key/value pairs that, for
201  * example, are used to expand placeholders in polkit authentication
202  * messages that are formatted like "Authentication required to access
203  * $(device)". For this example, when a key "device" exists in the map,
204  * the "$(device)" will be replaced by the corresponding value in the map.
205  *
206  * \see checkAuthorization(const QString&, const Subject&, AuthorizationFlags) Base version of this method.
207  */
208  // TODO: merge with checkAuthorization when we decide to break binary compatibility probably in Plasma 6
209  void checkAuthorizationWithDetails(
210  const QString &actionId, const Subject &subject,
211  AuthorizationFlags flags, const DetailsMap &details);
212 
213  /**
214  * Synchronous version of the checkAuthorization method.
215  *
216  * \param actionId the Id of the action in question
217  * \param subject subject that the action is authorized for (e.g. unix process)
218  * \param flags flags that influences the authorization checking
219  *
220  * \see checkAuthorization Asynchronous version of this method.
221  */
222  Result checkAuthorizationSync(const QString &actionId, const Subject &subject,
223  AuthorizationFlags flags);
224 
225  /**
226  * This function does the same as checkAuthorizationSync(const QString&,
227  * const Subject&, AuthorizationFlags), but also accepts a DetailsMap
228  * parameter.
229  *
230  * \see checkAuthorization(const QString&, const Subject&, AuthorizationFlags, const DetailsMap&) for a description of the details parameter.
231  *
232  * \see checkAuthorizationSync(const QString&, const Subject, AuthorizationFlags) Base version of this method.
233  */
234  Result checkAuthorizationSyncWithDetails(const QString &actionId, const Subject &subject,
235  AuthorizationFlags flags, const DetailsMap &details);
236 
237  /**
238  * This method can be used to cancel last authorization check.
239  */
240  void checkAuthorizationCancel();
241 
242  /**
243  * Asynchronously retrieves all registered actions.
244  *
245  * When operation is finished, signal checkAuthorizationFinish is emitted
246  * with result of authorization check in its parameter.
247  *
248  * \see enumerateActionsSync Synchronous version of this method.
249  * \see enumerateActionsFinished Signal that is emitted when this method finishes.
250  * \see enumerateActionsCancel Use it to cancel execution of this method.
251  */
252  void enumerateActions();
253 
254  /**
255  * Synchronously retrieves all registered actions.
256  *
257  * \see enumerateActions Asynchronous version of this method.
258  *
259  * \return a list of Action IDs
260  */
261  ActionDescription::List enumerateActionsSync();
262 
263  /**
264  * This method can be used to cancel enumeration of actions
265  */
266  void enumerateActionsCancel();
267 
268  /**
269  * Registers an authentication agent.
270  *
271  * \see registerAuthenticationAgentSync Synchronous version of this method.
272  * \see registerAuthenticationAgentFinished Signal that is emitted when this method finishes.
273  * \see registerAuthenticationAgentCancel Use it to cancel execution of this method.
274  *
275  * \param subject caller subject
276  * \param locale the locale of the authentication agent
277  * \param objectPath the object path for the authentication agent
278  */
279  void registerAuthenticationAgent(const Subject &subject, const QString &locale,
280  const QString &objectPath);
281 
282  /**
283  * Registers an authentication agent.
284  *
285  * \see registerAuthenticationAgent Asynchronous version of this method.
286  *
287  * \param subject caller subject
288  * \param locale the locale of the authentication agent
289  * \param objectPath the object path for the authentication agent
290  *
291  * \return \c true if the Authentication agent has been successfully registered
292  * \c false if the Authentication agent registration failed
293  */
294  bool registerAuthenticationAgentSync(const Subject &subject, const QString &locale,
295  const QString &objectPath);
296 
297  /**
298  * This method can be used to cancel the registration of the authentication agent.
299  */
300  void registerAuthenticationAgentCancel();
301 
302  /**
303  * Unregisters an Authentication agent.
304  *
305  * \see unregisterAuthenticationAgentSync Synchronous version of this method.
306  * \see unregisterAuthenticationAgentFinished Signal that is emitted when this method finishes.
307  * \see unregisterAuthenticationAgentCancel Use it to cancel execution of this method.
308  *
309  * \param subject caller subject
310  * \param objectPath the object path for the Authentication agent
311  *
312  * \return \c true if the Authentication agent has been successfully unregistered
313  * \c false if the Authentication agent unregistration failed
314  */
315  void unregisterAuthenticationAgent(const Subject &subject, const QString &objectPath);
316 
317  /**
318  * Unregisters an Authentication agent.
319  *
320  * \see unregisterAuthenticationAgent Asynchronous version of this method.
321  *
322  * \param subject caller subject
323  * \param objectPath the object path for the Authentication agent
324  *
325  * \return \c true if the Authentication agent has been successfully unregistered
326  * \c false if the Authentication agent unregistration failed
327  */
328  bool unregisterAuthenticationAgentSync(const Subject &subject, const QString &objectPath);
329 
330  /**
331  * This method can be used to cancel the unregistration of the authentication agent.
332  */
333  void unregisterAuthenticationAgentCancel();
334 
335  /**
336  * Provide response that \p identity successfully authenticated for the authentication request identified by \p cookie.
337  *
338  * \see authenticationAgentResponseSync Synchronous version of this method.
339  * \see authenticationAgentResponseFinished Signal that is emitted when this method finishes.
340  * \see authenticationAgentResponseCancel Use it to cancel execution of this method.
341  *
342  * \param cookie The cookie passed to the authentication agent from the authority.
343  * \param identity The identity that was authenticated.
344  */
345  void authenticationAgentResponse(const QString &cookie, const Identity &identity);
346 
347  /**
348  * Provide response that \p identity successfully authenticated for the authentication request identified by \p cookie.
349  *
350  * \see authenticationAgentResponse Asynchronous version of this method.
351  *
352  * \param cookie The cookie passed to the authentication agent from the authority.
353  * \param identity The identity that was authenticated.
354  *
355  * \return \c true if authority acknowledged the call, \c false if error is set.
356  *
357  */
358  bool authenticationAgentResponseSync(const QString& cookie, const PolkitQt1::Identity& identity);
359 
360  /**
361  * This method can be used to cancel the authenticationAgentResponseAsync method.
362  */
363  void authenticationAgentResponseCancel();
364 
365  /**
366  * Retrieves all temporary action that applies to \p subject.
367  *
368  * \see enumerateTemporaryAuthorizationsSync Synchronous version of this method.
369  * \see enumerateTemporaryAuthorizationsFinished Signal that is emitted when this method finishes.
370  * \see enumerateTemporaryAuthorizationsCancel Use it to cancel execution of this method.
371  *
372  * \param subject the subject to get temporary authorizations for
373  *
374  */
375  void enumerateTemporaryAuthorizations(const Subject &subject);
376 
377  /**
378  * Retrieves all temporary action that applies to \p subject
379  *
380  * \see enumerateTemporaryAuthorizations Asynchronous version of this method.
381  *
382  * \param subject the subject to get temporary authorizations for
383  *
384  * \note Free all TemporaryAuthorization objects using \p delete operator.
385  *
386  * \return List of all temporary authorizations
387  */
388  TemporaryAuthorization::List enumerateTemporaryAuthorizationsSync(const Subject &subject);
389 
390  /**
391  * This method can be used to cancel the enumerateTemporaryAuthorizationsAsync method.
392  */
393  void enumerateTemporaryAuthorizationsCancel();
394 
395  /**
396  * Revokes all temporary authorizations that applies to \p subject
397  *
398  * \see revokeTemporaryAuthorizationsSync Synchronous version of this method.
399  * \see revokeTemporaryAuthorizationsFinished Signal that is emitted when this method finishes.
400  * \see revokeTemporaryAuthorizationsCancel Use it to cancel execution of this method.
401 
402  * \param subject the subject to revoke temporary authorizations from
403  */
404  void revokeTemporaryAuthorizations(const Subject &subject);
405 
406  /**
407  * Revokes all temporary authorizations that applies to \p subject
408  *
409  * \see revokeTemporaryAuthorizations Asynchronous version of this method.
410  *
411  * \param subject the subject to revoke temporary authorizations from
412  *
413  * \return \c true if all temporary authorization were revoked
414  * \c false if the revoking failed
415  */
416  bool revokeTemporaryAuthorizationsSync(const Subject &subject);
417 
418  /**
419  * This method can be used to cancel the method revokeTemporaryAuthorizationsAsync.
420  */
421  void revokeTemporaryAuthorizationsCancel();
422 
423  /**
424  * Revokes temporary authorization by \p id
425  *
426  * \see revokeTemporaryAuthorizationSync Synchronous version of this method.
427  * \see revokeTemporaryAuthorizationFinished Signal that is emitted when this method finishes.
428  * \see revokeTemporaryAuthorizationCancel Use it to cancel execution of this method.
429  *
430  * \param id the identifier of the temporary authorization
431  */
432  void revokeTemporaryAuthorization(const QString &id);
433 
434  /**
435  * Revokes temporary authorization by \p id
436  *
437  * \see revokeTemporaryAuthorization Asynchronous version of this method.
438  *
439  * \param id the identifier of the temporary authorization
440  *
441  * \return \c true if the temporary authorization was revoked
442  * \c false if the revoking failed
443  */
444  bool revokeTemporaryAuthorizationSync(const QString &id);
445 
446  /**
447  * This method can be used to cancel the method revokeTemporaryAuthorizationAsync.
448  */
449  void revokeTemporaryAuthorizationCancel();
450 
451 Q_SIGNALS:
452  /**
453  * This signal will be emitted when a configuration
454  * file gets changed (e.g. /etc/PolicyKit/PolicyKit.conf or
455  * .policy files).
456  * Connect to this signal if you want to track down
457  * actions.
458  */
459  void configChanged();
460 
461  /**
462  * This signal is emitted when ConsoleKit configuration
463  * changes. This might happen when a session becomes active
464  * or inactive.
465  *
466  * If you want to track your actions directly you should
467  * connect to this signal, as this might change the return value
468  * PolicyKit will give you.
469  *
470  * \note If you use Action you'll probably prefer to
471  * use the dataChanged() signal to track Action changes.
472  */
473  void consoleKitDBChanged();
474 
475  /**
476  * This signal is emitted when asynchronous method checkAuthorization finishes.
477  *
478  * The argument is the result of authorization.
479  */
480  void checkAuthorizationFinished(PolkitQt1::Authority::Result);
481 
482  /**
483  * This signal is emitted when asynchronous method enumerateActions finishes.
484  *
485  * The argument is the list of all Action IDs.
486  */
487  void enumerateActionsFinished(PolkitQt1::ActionDescription::List);
488 
489  /**
490  * This signal is emitted when asynchronous method registerAuthenticationAgent finishes.
491  *
492  * The argument is \c true if the Authentication agent has been successfully registered
493  * \c false if the Authentication agent registration failed
494  */
495  void registerAuthenticationAgentFinished(bool);
496 
497  /**
498  * This signal is emitted when asynchronous method unregisterAuthenticationAgent finishes.
499  *
500  * The argument is \c true if the Authentication agent has been successfully unregistered
501  * \c false if the Authentication agent unregistration failed
502  */
503  void unregisterAuthenticationAgentFinished(bool);
504 
505  /**
506  * This signal is emitted when asynchronous method authenticationAgentResponse finishes.
507  *
508  * The argument is \c true if authority acknowledged the call, \c false if error is set.
509  */
510  void authenticationAgentResponseFinished(bool);
511 
512  /**
513  * This signal is emitted when asynchronous method enumerateTemporaryAuthorizations finishes.
514  *
515  * The argument is list of all temporary authorizations.
516  *
517  * \note Free all TemporaryAuthorization objects using \p delete operator.
518  */
519  void enumerateTemporaryAuthorizationsFinished(PolkitQt1::TemporaryAuthorization::List);
520 
521  /**
522  * This signal is emitted when asynchronous method revokeTemporaryAuthorizations finishes.
523  *
524  * The argument is \c true if all temporary authorizations were revoked
525  * \c false if the revoking failed
526  */
527  void revokeTemporaryAuthorizationsFinished(bool);
528 
529  /**
530  * This signal is emitted when asynchronous method revokeTemporaryAuthorization finishes.
531  * \return \c true if the temporary authorization was revoked
532  * \c false if the revoking failed
533  */
534  void revokeTemporaryAuthorizationFinished(bool);
535 
536 private:
537  explicit Authority(PolkitAuthority *context, QObject *parent = nullptr);
538 
539  class Private;
540  friend class Private;
541  Private * const d;
542 
543  Q_PRIVATE_SLOT(d, void dbusFilter(const QDBusMessage &message))
544 };
545 
546 Q_DECLARE_OPERATORS_FOR_FLAGS(Authority::AuthorizationFlags)
547 
548 }
549 
550 #endif
This class represents PolicyKit subjects.
Abstract class representing identities.
Convenience class for Qt/KDE applications.
ErrorCode
Error codes for the authority class.
Namespace wrapping Polkit-Qt classes.
QString message
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Wed Jun 7 2023 03:57:31 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.