File indexing completed on 2024-04-14 04:38:31
0001 /* 0002 This file is part of the Polkit-qt project 0003 SPDX-FileCopyrightText: 2009 Daniel Nicoletti <dantti85-pk@yahoo.com.br> 0004 SPDX-FileCopyrightText: 2009 Dario Freddi <drf@kde.org> 0005 SPDX-FileCopyrightText: 2009 Jaroslav Reznik <jreznik@redhat.com> 0006 SPDX-FileCopyrightText: 2009 Radek Novacek <rnovacek@redhat.com> 0007 0008 SPDX-License-Identifier: LGPL-2.0-or-later 0009 */ 0010 0011 #ifndef POLKITQT1_AUTHORITY_H 0012 #define POLKITQT1_AUTHORITY_H 0013 0014 #include "polkitqt1-core-export.h" 0015 #include "polkitqt1-identity.h" 0016 #include "polkitqt1-subject.h" 0017 #include "polkitqt1-temporaryauthorization.h" 0018 #include "polkitqt1-actiondescription.h" 0019 0020 #include <QObject> 0021 #include <QMetaType> 0022 #include <QStringList> 0023 0024 typedef struct _PolkitAuthority PolkitAuthority; 0025 0026 /** 0027 * \namespace PolkitQt1 PolkitQt 0028 * 0029 * \brief Namespace wrapping Polkit-Qt classes 0030 * 0031 * This namespace wraps all Polkit-Qt classes. 0032 */ 0033 namespace PolkitQt1 0034 { 0035 0036 typedef QMap<QString, QString> DetailsMap; 0037 0038 /** 0039 * \class Authority polkitqt1-authority.h Authority 0040 * \author Daniel Nicoletti <dantti85-pk@yahoo.com.br> 0041 * \author Dario Freddi <drf@kde.org> 0042 * \author Jaroslav Reznik <jreznik@redhat.com> 0043 * 0044 * \brief Convenience class for Qt/KDE applications 0045 * 0046 * This class is a singleton that provides makes easy the usage 0047 * of PolKitAuthority. It emits configChanged() 0048 * whenever PolicyKit files change (e.g. the PolicyKit.conf 0049 * or .policy files) or when ConsoleKit reports activities changes. 0050 * 0051 * \note This class is a singleton, its constructor is private. 0052 * Call Authority::instance() to get an instance of the Authority object. 0053 * Do not delete Authority::instance(), cleanup will be done automatically. 0054 */ 0055 class POLKITQT1_CORE_EXPORT Authority : public QObject 0056 { 0057 Q_OBJECT 0058 Q_DISABLE_COPY(Authority) 0059 public: 0060 enum Result { 0061 /** Result unknown */ 0062 Unknown = 0x00, 0063 /** The subject is authorized for the specified action */ 0064 Yes = 0x01, 0065 /** The subject is not authorized for the specified action */ 0066 No = 0x02, 0067 /** The subject is authorized if more information is provided */ 0068 Challenge = 0x03 0069 }; 0070 Q_ENUM(Result) 0071 0072 enum AuthorizationFlag { 0073 /** No flags set **/ 0074 None = 0x00, 0075 /** If the subject can obtain the authorization through authentication, 0076 * and an authentication agent is available, then attempt to do so. 0077 * 0078 * Note, this means that the method used for checking authorization is likely 0079 * to block for a long time. **/ 0080 AllowUserInteraction = 0x01 0081 }; 0082 Q_DECLARE_FLAGS(AuthorizationFlags, AuthorizationFlag) 0083 0084 /** Error codes for the authority class */ 0085 enum ErrorCode { 0086 /** No error occurred **/ 0087 E_None = 0x00, 0088 /** Authority cannot be obtained **/ 0089 E_GetAuthority = 0x01, 0090 /** Authority check failed **/ 0091 E_CheckFailed = 0x02, 0092 /** Wrong or empty subject was given **/ 0093 E_WrongSubject = 0x03, 0094 /** Action returned unknown result **/ 0095 E_UnknownResult = 0x04, 0096 /** Enumerating actions failed **/ 0097 E_EnumFailed = 0x05, 0098 /** Registration of authentication agent failed **/ 0099 E_RegisterFailed = 0x06, 0100 /** Unregistration of authentication agent failed **/ 0101 E_UnregisterFailed = 0x07, 0102 /** Cookie or polkitqt1-identity.handled to the action is empty **/ 0103 E_CookieOrIdentityEmpty = 0x08, 0104 /** Response of auth agent failed **/ 0105 E_AgentResponseFailed = 0x09, 0106 /** Revoke temporary authorizations failed **/ 0107 E_RevokeFailed = 0x0A 0108 }; 0109 Q_ENUM(ErrorCode) 0110 0111 /** 0112 * \brief Returns the instance of Authority 0113 * 0114 * Returns the current instance of Authority. Call this function whenever 0115 * you need to access the Authority class. 0116 * 0117 * \note Authority is a singleton. Memory is handled by polkit-qt, so you just 0118 * need to call this function to get a working instance of Authority. 0119 * Don't delete the object after having used it. 0120 * 0121 * \param authority use this if you want to set an explicit PolkitAuthority. If you 0122 * don't know what this implies, simply ignore the parameter. In case 0123 * you want to use it, be sure of streaming it the first time you call 0124 * this function, otherwise it will have no effect. 0125 * 0126 * \return The current authority instance 0127 */ 0128 static Authority *instance(PolkitAuthority *authority = nullptr); 0129 0130 ~Authority() override; 0131 0132 /** 0133 * You should always call this method after every action. No action will be allowed 0134 * if the object is in error state. Use clearError() to clear the error message. 0135 * 0136 * \see lastError 0137 * \see clearError 0138 * 0139 * \return \c true if an error occurred, \c false if the library is ready 0140 */ 0141 bool hasError() const; 0142 0143 /** 0144 * \return the code of last error 0145 */ 0146 ErrorCode lastError() const; 0147 0148 /** 0149 * Get detail information about error that occurred. 0150 * 0151 * \return detail message 0152 */ 0153 const QString errorDetails() const; 0154 0155 /** 0156 * Use this method to clear the error message. 0157 */ 0158 void clearError(); 0159 0160 /** 0161 * Returns the current instance of PolkitAuthority. If you are handling 0162 * it through Polkit-qt (which is quite likely, since you are calling 0163 * this function), DO NOT use any PolicyKit API's specific method that 0164 * modifies the instance on it, unless you're completely aware of what you're doing and 0165 * of the possible consequencies. Use this instance only to gather information. 0166 * 0167 * \return the current PolkitAuthority instance 0168 */ 0169 PolkitAuthority *polkitAuthority() const; 0170 0171 /** 0172 * This function should be used by mechanisms (e.g.: helper applications). 0173 * It returns the action should be carried out, so if the caller was 0174 * actually authorized to perform it. The result is in form of a Result, so that 0175 * you can have more control over the whole process, and detect an eventual error. 0176 * Most of the times you simply want to check if the result is == to \c Result::Yes, 0177 * if you don't have specific needs. 0178 * 0179 * It is CRITICAL that you call this function 0180 * and check what it returns before doing anything in your helper, since otherwise 0181 * you could be actually performing an action from an unknown or unauthorized caller. 0182 * 0183 * When operation is finished, signal checkAuthorizationFinish is emitted 0184 * with result of authorization check in its parameter. 0185 * 0186 * \see checkAuthorizationSync Synchronous version of this method. 0187 * \see checkAuthorizationFinished Signal that is emitted when this method finishes. 0188 * \see checkAuthorizationCancel Use it to cancel execution of this method. 0189 * 0190 * \param actionId the Id of the action in question 0191 * \param subject subject that the action is authorized for (e.g. unix process) 0192 * \param flags flags that influences the authorization checking 0193 */ 0194 void checkAuthorization(const QString &actionId, const Subject &subject, 0195 AuthorizationFlags flags); 0196 0197 /** 0198 * This function does the same as checkAuthorization(const QString&, const 0199 * Subject&, AuthorizationFlags), but also accepts a 0200 * DetailsMap parameter. This map can contain key/value pairs that, for 0201 * example, are used to expand placeholders in polkit authentication 0202 * messages that are formatted like "Authentication required to access 0203 * $(device)". For this example, when a key "device" exists in the map, 0204 * the "$(device)" will be replaced by the corresponding value in the map. 0205 * 0206 * \see checkAuthorization(const QString&, const Subject&, AuthorizationFlags) Base version of this method. 0207 */ 0208 // TODO: merge with checkAuthorization when we decide to break binary compatibility probably in Plasma 6 0209 void checkAuthorizationWithDetails( 0210 const QString &actionId, const Subject &subject, 0211 AuthorizationFlags flags, const DetailsMap &details); 0212 0213 /** 0214 * Synchronous version of the checkAuthorization method. 0215 * 0216 * \param actionId the Id of the action in question 0217 * \param subject subject that the action is authorized for (e.g. unix process) 0218 * \param flags flags that influences the authorization checking 0219 * 0220 * \see checkAuthorization Asynchronous version of this method. 0221 */ 0222 Result checkAuthorizationSync(const QString &actionId, const Subject &subject, 0223 AuthorizationFlags flags); 0224 0225 /** 0226 * This function does the same as checkAuthorizationSync(const QString&, 0227 * const Subject&, AuthorizationFlags), but also accepts a DetailsMap 0228 * parameter. 0229 * 0230 * \see checkAuthorization(const QString&, const Subject&, AuthorizationFlags, const DetailsMap&) for a description of the details parameter. 0231 * 0232 * \see checkAuthorizationSync(const QString&, const Subject, AuthorizationFlags) Base version of this method. 0233 */ 0234 Result checkAuthorizationSyncWithDetails(const QString &actionId, const Subject &subject, 0235 AuthorizationFlags flags, const DetailsMap &details); 0236 0237 /** 0238 * This method can be used to cancel last authorization check. 0239 */ 0240 void checkAuthorizationCancel(); 0241 0242 /** 0243 * Asynchronously retrieves all registered actions. 0244 * 0245 * When operation is finished, signal checkAuthorizationFinish is emitted 0246 * with result of authorization check in its parameter. 0247 * 0248 * \see enumerateActionsSync Synchronous version of this method. 0249 * \see enumerateActionsFinished Signal that is emitted when this method finishes. 0250 * \see enumerateActionsCancel Use it to cancel execution of this method. 0251 */ 0252 void enumerateActions(); 0253 0254 /** 0255 * Synchronously retrieves all registered actions. 0256 * 0257 * \see enumerateActions Asynchronous version of this method. 0258 * 0259 * \return a list of Action IDs 0260 */ 0261 ActionDescription::List enumerateActionsSync(); 0262 0263 /** 0264 * This method can be used to cancel enumeration of actions 0265 */ 0266 void enumerateActionsCancel(); 0267 0268 /** 0269 * Registers an authentication agent. 0270 * 0271 * \see registerAuthenticationAgentSync Synchronous version of this method. 0272 * \see registerAuthenticationAgentFinished Signal that is emitted when this method finishes. 0273 * \see registerAuthenticationAgentCancel Use it to cancel execution of this method. 0274 * 0275 * \param subject caller subject 0276 * \param locale the locale of the authentication agent 0277 * \param objectPath the object path for the authentication agent 0278 */ 0279 void registerAuthenticationAgent(const Subject &subject, const QString &locale, 0280 const QString &objectPath); 0281 0282 /** 0283 * Registers an authentication agent. 0284 * 0285 * \see registerAuthenticationAgent Asynchronous version of this method. 0286 * 0287 * \param subject caller subject 0288 * \param locale the locale of the authentication agent 0289 * \param objectPath the object path for the authentication agent 0290 * 0291 * \return \c true if the Authentication agent has been successfully registered 0292 * \c false if the Authentication agent registration failed 0293 */ 0294 bool registerAuthenticationAgentSync(const Subject &subject, const QString &locale, 0295 const QString &objectPath); 0296 0297 /** 0298 * This method can be used to cancel the registration of the authentication agent. 0299 */ 0300 void registerAuthenticationAgentCancel(); 0301 0302 /** 0303 * Unregisters an Authentication agent. 0304 * 0305 * \see unregisterAuthenticationAgentSync Synchronous version of this method. 0306 * \see unregisterAuthenticationAgentFinished Signal that is emitted when this method finishes. 0307 * \see unregisterAuthenticationAgentCancel Use it to cancel execution of this method. 0308 * 0309 * \param subject caller subject 0310 * \param objectPath the object path for the Authentication agent 0311 * 0312 * \return \c true if the Authentication agent has been successfully unregistered 0313 * \c false if the Authentication agent unregistration failed 0314 */ 0315 void unregisterAuthenticationAgent(const Subject &subject, const QString &objectPath); 0316 0317 /** 0318 * Unregisters an Authentication agent. 0319 * 0320 * \see unregisterAuthenticationAgent Asynchronous version of this method. 0321 * 0322 * \param subject caller subject 0323 * \param objectPath the object path for the Authentication agent 0324 * 0325 * \return \c true if the Authentication agent has been successfully unregistered 0326 * \c false if the Authentication agent unregistration failed 0327 */ 0328 bool unregisterAuthenticationAgentSync(const Subject &subject, const QString &objectPath); 0329 0330 /** 0331 * This method can be used to cancel the unregistration of the authentication agent. 0332 */ 0333 void unregisterAuthenticationAgentCancel(); 0334 0335 /** 0336 * Provide response that \p identity successfully authenticated for the authentication request identified by \p cookie. 0337 * 0338 * \see authenticationAgentResponseSync Synchronous version of this method. 0339 * \see authenticationAgentResponseFinished Signal that is emitted when this method finishes. 0340 * \see authenticationAgentResponseCancel Use it to cancel execution of this method. 0341 * 0342 * \param cookie The cookie passed to the authentication agent from the authority. 0343 * \param identity The identity that was authenticated. 0344 */ 0345 void authenticationAgentResponse(const QString &cookie, const Identity &identity); 0346 0347 /** 0348 * Provide response that \p identity successfully authenticated for the authentication request identified by \p cookie. 0349 * 0350 * \see authenticationAgentResponse Asynchronous version of this method. 0351 * 0352 * \param cookie The cookie passed to the authentication agent from the authority. 0353 * \param identity The identity that was authenticated. 0354 * 0355 * \return \c true if authority acknowledged the call, \c false if error is set. 0356 * 0357 */ 0358 bool authenticationAgentResponseSync(const QString& cookie, const PolkitQt1::Identity& identity); 0359 0360 /** 0361 * This method can be used to cancel the authenticationAgentResponseAsync method. 0362 */ 0363 void authenticationAgentResponseCancel(); 0364 0365 /** 0366 * Retrieves all temporary action that applies to \p subject. 0367 * 0368 * \see enumerateTemporaryAuthorizationsSync Synchronous version of this method. 0369 * \see enumerateTemporaryAuthorizationsFinished Signal that is emitted when this method finishes. 0370 * \see enumerateTemporaryAuthorizationsCancel Use it to cancel execution of this method. 0371 * 0372 * \param subject the subject to get temporary authorizations for 0373 * 0374 */ 0375 void enumerateTemporaryAuthorizations(const Subject &subject); 0376 0377 /** 0378 * Retrieves all temporary action that applies to \p subject 0379 * 0380 * \see enumerateTemporaryAuthorizations Asynchronous version of this method. 0381 * 0382 * \param subject the subject to get temporary authorizations for 0383 * 0384 * \note Free all TemporaryAuthorization objects using \p delete operator. 0385 * 0386 * \return List of all temporary authorizations 0387 */ 0388 TemporaryAuthorization::List enumerateTemporaryAuthorizationsSync(const Subject &subject); 0389 0390 /** 0391 * This method can be used to cancel the enumerateTemporaryAuthorizationsAsync method. 0392 */ 0393 void enumerateTemporaryAuthorizationsCancel(); 0394 0395 /** 0396 * Revokes all temporary authorizations that applies to \p subject 0397 * 0398 * \see revokeTemporaryAuthorizationsSync Synchronous version of this method. 0399 * \see revokeTemporaryAuthorizationsFinished Signal that is emitted when this method finishes. 0400 * \see revokeTemporaryAuthorizationsCancel Use it to cancel execution of this method. 0401 0402 * \param subject the subject to revoke temporary authorizations from 0403 */ 0404 void revokeTemporaryAuthorizations(const Subject &subject); 0405 0406 /** 0407 * Revokes all temporary authorizations that applies to \p subject 0408 * 0409 * \see revokeTemporaryAuthorizations Asynchronous version of this method. 0410 * 0411 * \param subject the subject to revoke temporary authorizations from 0412 * 0413 * \return \c true if all temporary authorization were revoked 0414 * \c false if the revoking failed 0415 */ 0416 bool revokeTemporaryAuthorizationsSync(const Subject &subject); 0417 0418 /** 0419 * This method can be used to cancel the method revokeTemporaryAuthorizationsAsync. 0420 */ 0421 void revokeTemporaryAuthorizationsCancel(); 0422 0423 /** 0424 * Revokes temporary authorization by \p id 0425 * 0426 * \see revokeTemporaryAuthorizationSync Synchronous version of this method. 0427 * \see revokeTemporaryAuthorizationFinished Signal that is emitted when this method finishes. 0428 * \see revokeTemporaryAuthorizationCancel Use it to cancel execution of this method. 0429 * 0430 * \param id the identifier of the temporary authorization 0431 */ 0432 void revokeTemporaryAuthorization(const QString &id); 0433 0434 /** 0435 * Revokes temporary authorization by \p id 0436 * 0437 * \see revokeTemporaryAuthorization Asynchronous version of this method. 0438 * 0439 * \param id the identifier of the temporary authorization 0440 * 0441 * \return \c true if the temporary authorization was revoked 0442 * \c false if the revoking failed 0443 */ 0444 bool revokeTemporaryAuthorizationSync(const QString &id); 0445 0446 /** 0447 * This method can be used to cancel the method revokeTemporaryAuthorizationAsync. 0448 */ 0449 void revokeTemporaryAuthorizationCancel(); 0450 0451 Q_SIGNALS: 0452 /** 0453 * This signal will be emitted when a configuration 0454 * file gets changed (e.g. /etc/PolicyKit/PolicyKit.conf or 0455 * .policy files). 0456 * Connect to this signal if you want to track down 0457 * actions. 0458 */ 0459 void configChanged(); 0460 0461 /** 0462 * This signal is emitted when ConsoleKit configuration 0463 * changes. This might happen when a session becomes active 0464 * or inactive. 0465 * 0466 * If you want to track your actions directly you should 0467 * connect to this signal, as this might change the return value 0468 * PolicyKit will give you. 0469 * 0470 * \note If you use Action you'll probably prefer to 0471 * use the dataChanged() signal to track Action changes. 0472 */ 0473 void consoleKitDBChanged(); 0474 0475 /** 0476 * This signal is emitted when asynchronous method checkAuthorization finishes. 0477 * 0478 * The argument is the result of authorization. 0479 */ 0480 void checkAuthorizationFinished(PolkitQt1::Authority::Result); 0481 0482 /** 0483 * This signal is emitted when asynchronous method enumerateActions finishes. 0484 * 0485 * The argument is the list of all Action IDs. 0486 */ 0487 void enumerateActionsFinished(PolkitQt1::ActionDescription::List); 0488 0489 /** 0490 * This signal is emitted when asynchronous method registerAuthenticationAgent finishes. 0491 * 0492 * The argument is \c true if the Authentication agent has been successfully registered 0493 * \c false if the Authentication agent registration failed 0494 */ 0495 void registerAuthenticationAgentFinished(bool); 0496 0497 /** 0498 * This signal is emitted when asynchronous method unregisterAuthenticationAgent finishes. 0499 * 0500 * The argument is \c true if the Authentication agent has been successfully unregistered 0501 * \c false if the Authentication agent unregistration failed 0502 */ 0503 void unregisterAuthenticationAgentFinished(bool); 0504 0505 /** 0506 * This signal is emitted when asynchronous method authenticationAgentResponse finishes. 0507 * 0508 * The argument is \c true if authority acknowledged the call, \c false if error is set. 0509 */ 0510 void authenticationAgentResponseFinished(bool); 0511 0512 /** 0513 * This signal is emitted when asynchronous method enumerateTemporaryAuthorizations finishes. 0514 * 0515 * The argument is list of all temporary authorizations. 0516 * 0517 * \note Free all TemporaryAuthorization objects using \p delete operator. 0518 */ 0519 void enumerateTemporaryAuthorizationsFinished(PolkitQt1::TemporaryAuthorization::List); 0520 0521 /** 0522 * This signal is emitted when asynchronous method revokeTemporaryAuthorizations finishes. 0523 * 0524 * The argument is \c true if all temporary authorizations were revoked 0525 * \c false if the revoking failed 0526 */ 0527 void revokeTemporaryAuthorizationsFinished(bool); 0528 0529 /** 0530 * This signal is emitted when asynchronous method revokeTemporaryAuthorization finishes. 0531 * \return \c true if the temporary authorization was revoked 0532 * \c false if the revoking failed 0533 */ 0534 void revokeTemporaryAuthorizationFinished(bool); 0535 0536 private: 0537 explicit Authority(PolkitAuthority *context, QObject *parent = nullptr); 0538 0539 class Private; 0540 friend class Private; 0541 Private * const d; 0542 0543 Q_PRIVATE_SLOT(d, void dbusFilter(const QDBusMessage &message)) 0544 }; 0545 0546 Q_DECLARE_OPERATORS_FOR_FLAGS(Authority::AuthorizationFlags) 0547 0548 } 0549 0550 #endif