README.md
1# KAuth
2
3Execute actions as privileged user
4
5## Introduction
6
7KAuth provides a convenient, system-integrated way to offload actions that need
8to be performed as a privileged user (root, for example) to small (hopefully
9secure) helper utilities.
10
11## Usage
12
13If you are using CMake, you need to have
14
15 find_package(KF5Auth NO_MODULE)
16
17(or find KF5 with the Auth component) in your CMakeLists.txt file. You need
18to link to KF5::AuthCore, or KF5::Auth if you need KAuth::ObjectDecorator.
19
20Executing privileged actions typically involves having a minimal helper utility
21that does the actual work, and calling that utility with escalated privileges if
22the user has permission to do so (often requiring the user to enter appropriate
23credentials, like entering a password).
24
25Therefore, use of the KAuth library is in two parts. In the main part of your
26code, you use KAuth::Action (and specifically KAuth::Action::execute()) when you
27need to do something privileged, like write to a file normally only writable by
28root.
29
30The code that actually performs that action, such as writing to a file, needs to
31be placed in the slot of a helper QObject class, which should use the methods of
32KAuth::HelperSupport and be compiled into an executable. You will also want to
33use the `kauth_install_helper_files` and `kauth_install_actions` macros in your
34CMakeLists.txt.
35
36See <http://techbase.kde.org/Development/Tutorials/KAuth/KAuth_Basics> for a
37detailed tutorial on how to use KAuth.
38
39