File indexing completed on 2024-11-10 12:17:53
0001 /* 0002 SPDX-FileCopyrightText: 2008 Nicola Gigante <nicola.gigante@gmail.com> 0003 SPDX-FileCopyrightText: 2009-2012 Dario Freddi <drf@kde.org> 0004 0005 SPDX-License-Identifier: LGPL-2.1-or-later 0006 */ 0007 0008 #ifndef KAUTH_ACTION_REPLY_H 0009 #define KAUTH_ACTION_REPLY_H 0010 0011 #include "kauthcore_export.h" 0012 0013 #include <QDataStream> 0014 #include <QMap> 0015 #include <QSharedDataPointer> 0016 #include <QString> 0017 #include <QVariant> 0018 0019 /** 0020 @namespace KAuth 0021 0022 @section kauth_intro Introduction 0023 0024 The KDE Authorization API allows developers to write desktop applications that 0025 run high-privileged tasks in an easy, secure and cross-platform way. 0026 Previously, if an application had to do administrative tasks, it had to be run 0027 as root, using mechanisms such as sudo or graphical equivalents, or by setting 0028 the executable's setuid bit. This approach has some drawbacks. For example, the 0029 whole application code, including GUI handling and network communication, had 0030 to be done as root. More code that runs as root means more possible security 0031 holes. 0032 0033 The solution is the caller/helper pattern. With this pattern, the privileged 0034 code is isolated in a small helper tool that runs as root. This tool includes 0035 only the few lines of code that actually need to be run with privileges, not 0036 the whole application logic. All the other parts of the application are run as 0037 a normal user, and the helper tool is called when needed, using a secure 0038 mechanism that ensures that the user is authorized to do so. This pattern is 0039 not very easy to implement, because the developer has to deal with a lot of 0040 details about how to authorize the user, how to call the helper with the right 0041 privileges, how to exchange data with the helper, etc.. This is where the new 0042 KDE Authorization API becomes useful. Thanks to this new library, every 0043 developer can implement the caller/helper pattern to write application that 0044 require high privileges, with a few lines of code in an easy, secure and 0045 cross-platform way. 0046 0047 Not only: the library can also be used to lock down some actions in your 0048 application without using a helper but just checking for authorization and 0049 verifying if the user is allowed to perform it. 0050 0051 The KDE Authorization library uses different backends depending on the system 0052 where it's built. As far as the user authorization is concerned, it currently 0053 uses polkit-1 on linux and Authorization Services on Mac OSX, and a Windows 0054 backend will eventually be written, too. At the communication layer, the 0055 library uses D-Bus on every supported platform. 0056 0057 0058 @section kauth_concepts Concepts 0059 0060 There are a few concepts to understand when using the library. Much of those 0061 are carried from underlying APIs such as polkit-1, so if you know something 0062 about them there shouldn't be problems. 0063 0064 An <i>action</i> is a single task that needs to be done by the application. You 0065 refer to an action using an action identifier, which is a string in reverse 0066 domain name syntax (to avoid duplicates). For example, if the date/time control 0067 center module needs to change the date, it would need an action like 0068 "org.kde.datatime.change". If your application has to perform more than one 0069 privileged task, you should configure more than one action. This allows system 0070 administrators to fine tune the policies that allow users to perform your 0071 actions. 0072 0073 The <i>authorization</i> is the process that is executed to decide if a user 0074 can perform an action or not. In order to execute the helper as root, the user 0075 has to be authorized. For example, on linux, che policykit backend will look at 0076 the policykit policy database to see what requirements the user has to meet in 0077 order to execute the action you requested. The policy set for that action could 0078 allow or deny that user, or could say the user has to authenticate in order to 0079 gain the authorization. 0080 0081 The <i>authentication</i> is the process that allows the system to know that 0082 the person is in front of the console is who he says to be. If an action can be 0083 allowed or not depending on the user's identity, it has to be proved by 0084 entering a password or any other identification data the system requires. 0085 0086 A typical session with the authorization API is like this: 0087 - The user want to perform some privileged task 0088 - The application asks the system if the user is authorized. 0089 - The system asks the user to authenticate, if needed, and reply the application. 0090 - The application uses some system-provided mechanism to execute the helper's 0091 code as the root user. Previously, you had to set the setuid bit to do this, 0092 but we have something cool called 0093 "D-Bus activation" that doesn't require the setuid bit and is much more flexible. 0094 - The helper code, immediately after starting, checks if the caller is 0095 authorized to do what it asks. If not the helper immediately exits! 0096 - If the caller is authorized, the helper executes the task and exits. 0097 - The application receives data back from the helper. 0098 0099 All these steps are managed by the library. Following sections will focus on 0100 how to write the helper to implement your actions and how to call the helper 0101 from the application. 0102 0103 @section kauth_helper Writing the helper tool 0104 0105 The first thing you need to do before writing anything is to decide what 0106 actions you need to implement. Every action needs to be identified by a string 0107 in the reverse domain name syntax. This helps to avoid duplicates. An example 0108 of action id is "org.kde.datetime.change" or "org.kde.ksysguard.killprocess". 0109 Action names can only contain lowercase letters and dots (not as the first or 0110 last char). You also need an identifier for your helper. An application using 0111 the KDE auth api can implement and use more than one helper, implementing 0112 different actions. An helper is uniquely identified in the system context with 0113 a string. It, again, is in reverse domain name syntax to avoid duplicates. A 0114 common approach is to call the helper like the common prefix of your action 0115 names. For example, the Date/Time kcm module could use a helper called 0116 "org.kde.datetime", to perform actions like "org.kde.datetime.changedate" and 0117 "org.kde.datetime.changetime". This naming convention simplifies the 0118 implementation of the helper. 0119 0120 From the code point of view, the helper is implemented as a QObject subclass. 0121 Every action is implemented by a public slot. In the example/ directory in the 0122 source code tree you find a complete example. Let's look at that. The 0123 helper.h file declares the class that implements the helper. It looks like: 0124 0125 @snippet helper.cpp helper_declaration 0126 0127 The slot names are the last part of the action name, without the helper's ID if 0128 it's a prefix, with all the dots replaced by underscores. In this case, the 0129 helper ID is "org.kde.kf5auth.example", so those three slots implement the 0130 actions "org.kde.kf5auth.example.read", "org.kde.kf5auth.example.write" and 0131 "org.kde.kf5auth.example.longaction". The helper ID doesn't have to appear at 0132 the beginning of the action name, but it's good practice. If you want to extend 0133 MyHelper to implement also a different action like 0134 "org.kde.datetime.changetime", since the helper ID doesn't match you'll have to 0135 implement a slot called org_kde_datetime_changetime(). 0136 0137 The slot's signature is fixed: the return type is ActionReply, a class that 0138 allows you to return results, error codes and custom data to the application 0139 when your action has finished to run. 0140 0141 Let's look at the read action implementation. Its purpose is to read files: 0142 0143 @snippet helper.cpp helper_read_action 0144 0145 First, the code creates a default reply object. The default constructor creates 0146 a reply that reports success. Then it gets the filename parameter from the 0147 argument QVariantMap, that has previously been set by the application, before 0148 calling the helper. If it fails to open the file, it creates an ActionReply 0149 object that notifies that some error has happened in the helper, then set the 0150 error code to that returned by QFile and returns. If there is no error, it 0151 reads the file. The contents are added to the reply. 0152 0153 Because this class will be compiled into a standalone executable, we need a 0154 main() function and some code to initialize everything: you don't have to write 0155 it. Instead, you use the KAUTH_HELPER_MAIN() macro that will take care of 0156 everything. It's used like this: 0157 0158 @snippet helper.cpp helper_main 0159 0160 The first parameter is the string containing the helper identifier. Please note 0161 that you need to use this same string in the application's code to tell the 0162 library which helper to call, so please stay away from typos, because we don't 0163 have any way to detect them. The second parameter is the name of the helper's 0164 class. Your helper, if complex, can be composed of a lot of source files, but 0165 the important thing is to include this macro in at least one of them. 0166 0167 To build the helper, KDE macros provide a function named 0168 kauth_install_helper_files(). Use it in your cmake file like this: 0169 0170 @code 0171 add_executable(<helper_target> your sources...) 0172 target_link_libraries(<helper_target> your libraries...) 0173 install(TARGETS <helper_target> DESTINATION ${KAUTH_HELPER_INSTALL_DIR}) 0174 0175 kauth_install_helper_files(<helper_target> <helper_id> <user>) 0176 @endcode 0177 0178 As locale is not inherited, the auth helper will have the text codec explicitly set 0179 to use UTF-8. 0180 0181 The first argument is the cmake target name for the helper executable, which 0182 you have to build and install separately. Make sure to INSTALL THE HELPER IN 0183 @c ${KAUTH_HELPER_INSTALL_DIR}, otherwise @c kauth_install_helper_files will not work. The 0184 second argument is the helper id. Please be sure to don't misspell it, and to 0185 not quote it. The user parameter is the user that the helper has to be run as. 0186 It usually is root, but some actions could require less strict permissions, so 0187 you should use the right user where possible (for example the user apache if 0188 you have to mess with apache settings). Note that the target created by this 0189 macro already links to libkauth and QtCore. 0190 0191 @section kauth_actions Action registration 0192 0193 To be able to authorize the actions, they have to be added to the policy 0194 database. To do this in a cross-platform way, we provide a cmake macro. It 0195 looks like: 0196 @code 0197 kauth_install_actions(<helper_id> <actions definition file>) 0198 @endcode 0199 0200 The action definition file describes which actions are implemented by your code 0201 and which default security options they should have. It is a common text file 0202 in ini format, with one section for each action and some parameters. The 0203 definition for the read action is: 0204 0205 @verbatim 0206 [org.kde.kf5auth.example.read] 0207 Name=Read action 0208 Description=Read action description 0209 Policy=auth_admin 0210 Persistence=session 0211 @endverbatim 0212 0213 The name parameter is a text describing the action for <i>who reads the 0214 file</i>. The description parameter is the message shown to the user in the 0215 authentication dialog. It should be a finite phrase. The policy attribute 0216 specify the default rule that the user must satisfy to be authorized. Possible 0217 values are: 0218 - yes: the action should be always allowed 0219 - no: the action should be always denied 0220 - auth_self: the user should authenticate as itself 0221 - auth_admin: the user should authenticate as an administrator user 0222 0223 The persistence attribute is optional. It says how long an authorization should 0224 be retained for that action. The values could be: 0225 - session: the authorization persists until the user logs-out 0226 - always: the authorization will persist indefinitely 0227 0228 If this attribute is missing, the authorization will be queried every time. 0229 0230 @note Only the PolicyKit and polkit-1 backends use this attribute. 0231 @warning With the polkit-1 backend, 'session' and 'always' have the same meaning. 0232 They just make the authorization persists for a few minutes. 0233 0234 @section kauth_app Calling the helper from the application 0235 0236 Once the helper is ready, we need to call it from the main application. 0237 In examples/client.cpp you can see how this is done. To create a reference to 0238 an action, an object of type Action has to be created. Every Action object 0239 refers to an action by its action id. Two objects with the same action id will 0240 act on the same action. With an Action object, you can authorize and execute 0241 the action. To execute an action you need to retrieve an ExecuteJob, which is 0242 a standard KJob that you can run synchronously or asynchronously. 0243 See the KJob documentation (from KCoreAddons) for more details. 0244 0245 The piece of code that calls the action of the previous example is: 0246 0247 @snippet client.cpp client_how_to_call_helper 0248 0249 First of all, it creates the action object specifying the action id. Then it 0250 loads the filename (we want to read a forbidden file) into the arguments() 0251 QVariantMap, which will be directly passed to the helper in the read() slot's 0252 parameter. This example code uses a synchronous call to execute the action and 0253 retrieve the reply. If the reply succeeded, the reply data is retrieved from 0254 the returned QVariantMap object. Please note that you have 0255 to explicitly set the helper ID to the action: this is done for added safety, 0256 to prevent the caller from accidentally invoking a helper, and also because 0257 KAuth actions may be used without a helper attached (the default). 0258 0259 Please note that if your application is calling the helper multiple times it 0260 must do so from the same thread. 0261 0262 @section kauth_async Asynchronous calls, data reporting, and action termination 0263 0264 For a more advanced example, we look at the action 0265 "org.kde.kf5auth.example.longaction" in the example helper. This is an action 0266 that takes a long time to execute, so we need some features: 0267 - The helper needs to regularly send data to the application, to inform about 0268 the execution status. 0269 - The application needs to be able to stop the action execution if the user 0270 stops it or close the application. 0271 The example code follows: 0272 0273 @snippet helper.cpp helper_longaction 0274 0275 In this example, the action is only waiting a "long" time using a loop, but we 0276 can see some interesting line. The progress status is sent to the application 0277 using the HelperSupport::progressStep(int) and 0278 HelperSupport::progressStep(const QVariantMap &) methods. 0279 When those methods are called, the HelperProxy associated with this action 0280 will emit the HelperProxy::progressStep(const QString &, int) and 0281 HelperProxy::progressStepData(const QString &, const QVariantMap &) signals, 0282 respectively, reporting back the data to the application. 0283 The method that takes an integer argument is the one used here. 0284 Its meaning is application dependent, so you can use it as a sort of 0285 percentage. If you want to report custom data back to the application, you 0286 can use the other method that takes a QVariantMap object which is directly 0287 passed to the app. 0288 0289 In this example code, the loop exits when the HelperSupport::isStopped() 0290 returns true. This happens when the application calls the HelperProxy::stopAction() 0291 method on the corresponding action object. 0292 The stopAction() method, this way, asks the helper to 0293 stop the action execution. It's up to the helper to obbey to this request, and 0294 if it does so, it should return from the slot, _not_ exit. 0295 0296 @section kauth_other Other features 0297 0298 It doesn't happen very frequently that you code something that doesn't require 0299 some debugging, and you'll need some tool, even a basic one, to debug your 0300 helper code as well. For this reason, the KDE Authorization library provides a 0301 message handler for the Qt debugging system. This means that every call to 0302 qDebug() & co. will be reported to the application, and printed using the same 0303 qt debugging system, with the same debug level. If, in the helper code, you 0304 write something like: 0305 @code 0306 qDebug() << "I'm in the helper"; 0307 @endcode 0308 You'll see something like this in the <i>application</i>'s output: 0309 0310 @verbatim 0311 Debug message from the helper: I'm in the helper 0312 @endverbatim 0313 0314 Remember that the debug level is preserved, so if you use qFatal() you won't 0315 only abort the helper (which isn't suggested anyway), but also the application. 0316 0317 */ 0318 namespace KAuth 0319 { 0320 class ActionReplyData; 0321 0322 /** 0323 * @class ActionReply actionreply.h <KAuth/ActionReply> 0324 * 0325 * @brief Class that encapsulates a reply coming from the helper after executing 0326 * an action 0327 * 0328 * Helper applications will return this to describe the result of the action. 0329 * 0330 * Callers should access the reply though the KAuth::ExecuteJob job. 0331 * 0332 * @since 4.4 0333 */ 0334 class KAUTHCORE_EXPORT ActionReply 0335 { 0336 public: 0337 /** 0338 * Enumeration of the different kinds of replies. 0339 */ 0340 enum Type { 0341 KAuthErrorType, ///< An error reply generated by the library itself. 0342 HelperErrorType, ///< An error reply generated by the helper. 0343 SuccessType, ///< The action has been completed successfully 0344 }; 0345 0346 static const ActionReply SuccessReply(); ///< An empty successful reply. Same as using the default constructor 0347 static const ActionReply HelperErrorReply(); ///< An empty reply with type() == HelperError and errorCode() == -1 0348 static const ActionReply HelperErrorReply(int error); ///< An empty reply with type() == HelperError and error is set to the passed value 0349 0350 static const ActionReply NoResponderReply(); ///< errorCode() == NoResponder 0351 static const ActionReply NoSuchActionReply(); ///< errorCode() == NoSuchAction 0352 static const ActionReply InvalidActionReply(); ///< errorCode() == InvalidAction 0353 static const ActionReply AuthorizationDeniedReply(); ///< errorCode() == AuthorizationDenied 0354 static const ActionReply UserCancelledReply(); ///< errorCode() == UserCancelled 0355 static const ActionReply HelperBusyReply(); ///< errorCode() == HelperBusy 0356 static const ActionReply AlreadyStartedReply(); ///< errorCode() == AlreadyStartedError 0357 static const ActionReply DBusErrorReply(); ///< errorCode() == DBusError 0358 0359 /** 0360 * The enumeration of the possible values of errorCode() when type() is ActionReply::KAuthError 0361 */ 0362 enum Error { 0363 NoError = 0, ///< No error. 0364 NoResponderError, ///< The helper responder object hasn't been set. This shouldn't happen if you use the KAUTH_HELPER macro in the helper source 0365 NoSuchActionError, ///< The action you tried to execute doesn't exist. 0366 InvalidActionError, ///< You tried to execute an invalid action object 0367 AuthorizationDeniedError, ///< You don't have the authorization to execute the action 0368 UserCancelledError, ///< Action execution has been cancelled by the user 0369 HelperBusyError, ///< The helper is busy executing another action (or group of actions). Try later 0370 AlreadyStartedError, ///< The action was already started and is currently running 0371 DBusError, ///< An error from D-Bus occurred 0372 BackendError, ///< The underlying backend reported an error 0373 }; 0374 0375 /// Default constructor. Sets type() to Success and errorCode() to zero. 0376 ActionReply(); 0377 0378 /** 0379 * @brief Constructor to directly set the type. 0380 * 0381 * This constructor directly sets the reply type. You shouldn't need to 0382 * directly call this constructor, because you can use the more convenient 0383 * predefined replies constants. You also shouldn't create a reply with 0384 * the KAuthError type because it's reserved for errors coming from the 0385 * library. 0386 * 0387 * @param type The type of the new reply 0388 */ 0389 ActionReply(Type type); 0390 0391 /** 0392 * @brief Constructor that creates a KAuthError reply with a specified error code. 0393 * Do not use outside the library. 0394 * 0395 * This constructor is for internal use only, since it creates a reply 0396 * with KAuthError type, which is reserved for errors coming from the library. 0397 * 0398 * @param errorCode The error code of the new reply 0399 */ 0400 ActionReply(int errorCode); 0401 0402 /// Copy constructor 0403 ActionReply(const ActionReply &reply); 0404 0405 /// Virtual destructor 0406 virtual ~ActionReply(); 0407 0408 /** 0409 * @brief Sets the custom data to send back to the application 0410 * 0411 * In the helper's code you can use this function to set an QVariantMap 0412 * with custom data that will be sent back to the application. 0413 * 0414 * @param data The new QVariantMap object. 0415 */ 0416 void setData(const QVariantMap &data); 0417 0418 /** 0419 * @brief Returns the custom data coming from the helper. 0420 * 0421 * This method is used to get the object that contains the custom 0422 * data coming from the helper. In the helper's code, you can set it 0423 * using setData() or the convenience method addData(). 0424 * 0425 * @return The data coming from (or that will be sent by) the helper 0426 */ 0427 QVariantMap data() const; 0428 0429 /** 0430 * @brief Convenience method to add some data to the reply. 0431 * 0432 * This method adds the pair @c key/value to the QVariantMap used to 0433 * report back custom data to the application. 0434 * 0435 * Use this method if you don't want to create a new QVariantMap only to 0436 * add a new entry. 0437 * 0438 * @param key The new entry's key 0439 * @param value The value of the new entry 0440 */ 0441 void addData(const QString &key, const QVariant &value); 0442 0443 /// Returns the reply's type 0444 Type type() const; 0445 0446 /** 0447 * @brief Sets the reply type 0448 * 0449 * Every time you create an action reply, you implicitly set a type. 0450 * Default constructed replies or ActionReply::SuccessReply have 0451 * type() == Success. 0452 * ActionReply::HelperErrorReply has type() == HelperError. 0453 * Predefined error replies have type() == KAuthError. 0454 * 0455 * This means you rarely need to change the type after the creation, 0456 * but if you need to, don't set it to KAuthError, because it's reserved 0457 * for errors coming from the library. 0458 * 0459 * @param type The new reply type 0460 */ 0461 void setType(Type type); 0462 0463 /// Returns true if type() == Success 0464 bool succeeded() const; 0465 0466 /// Returns true if type() != Success 0467 bool failed() const; 0468 0469 /** 0470 * @brief Returns the error code of an error reply 0471 * 0472 * The error code returned is one of the values in the ActionReply::Error 0473 * enumeration if type() == KAuthError, or is totally application-dependent if 0474 * type() == HelperError. It also should be zero for successful replies. 0475 * 0476 * @return The reply error code 0477 */ 0478 int error() const; 0479 0480 /** 0481 * @brief Returns the error code of an error reply 0482 * 0483 * The error code returned is one of the values in the ActionReply::Error 0484 * enumeration if type() == KAuthError. 0485 * Result is only valid if the type() == HelperError 0486 * 0487 * @return The reply error code 0488 */ 0489 Error errorCode() const; 0490 0491 /** 0492 * @brief Sets the error code of an error reply 0493 * 0494 * If you're setting the error code in the helper because 0495 * you need to return an error to the application, please make sure 0496 * you already have set the type to HelperError, either by calling 0497 * setType() or by creating the reply in the right way. 0498 * 0499 * If the type is Success when you call this method, it will become KAuthError 0500 * 0501 * @param error The new reply error code 0502 */ 0503 void setError(int error); 0504 0505 /** 0506 * @brief Sets the error code of an error reply 0507 * 0508 * @see 0509 * If you're setting the error code in the helper, use setError(int) 0510 * 0511 * If the type is Success when you call this method, it will become KAuthError 0512 * 0513 * @param errorCode The new reply error code 0514 */ 0515 void setErrorCode(Error errorCode); 0516 0517 /** 0518 * @brief Gets a human-readble description of the error, if available 0519 * 0520 * Currently, replies of type KAuthError rarely report an error description. 0521 * This situation could change in the future. 0522 * 0523 * By now, you can use this method for custom errors of type HelperError. 0524 * 0525 * @return The error human-readable description 0526 */ 0527 QString errorDescription() const; 0528 0529 /** 0530 * @brief Sets a human-readble description of the error 0531 * 0532 * Call this method from the helper if you want to send back a description for 0533 * a custom error. Note that this method doesn't affect the errorCode in any way 0534 * 0535 * @param error The new error description 0536 */ 0537 void setErrorDescription(const QString &error); 0538 0539 /** 0540 * @brief Serialize the reply into a QByteArray. 0541 * 0542 * This is a convenience method used internally to sent the reply to a remote peer. 0543 * To recreate the reply, use deserialize() 0544 * 0545 * @return A QByteArray representation of this reply 0546 */ 0547 QByteArray serialized() const; 0548 0549 /** 0550 * @brief Deserialize a reply from a QByteArray 0551 * 0552 * This method returns a reply from a QByteArray obtained from 0553 * the serialized() method. 0554 * 0555 * @param data A QByteArray obtained with serialized() 0556 */ 0557 static ActionReply deserialize(const QByteArray &data); 0558 0559 /// Assignment operator 0560 ActionReply &operator=(const ActionReply &reply); 0561 0562 /** 0563 * @brief Comparison operator 0564 * 0565 * This operator checks if the type and the error code of two replies are the same. 0566 * It <b>doesn't</b> compare the data or the error descriptions, so be careful. 0567 * 0568 * The suggested use is to compare a reply against one of the predefined error replies: 0569 * @code 0570 * if(reply == ActionReply::HelperBusyReply) { 0571 * // Do something... 0572 * } 0573 * @endcode 0574 * 0575 * Note that you can do it also by compare errorCode() with the relative enumeration value. 0576 */ 0577 bool operator==(const ActionReply &reply) const; 0578 0579 /** 0580 * @brief Negated comparison operator 0581 * 0582 * See the operator==() for an important notice. 0583 */ 0584 bool operator!=(const ActionReply &reply) const; 0585 0586 private: 0587 QSharedDataPointer<ActionReplyData> d; 0588 }; 0589 0590 } // namespace Auth 0591 0592 Q_DECLARE_METATYPE(KAuth::ActionReply) 0593 0594 #endif