frameworks/kauth/README.md

0001 # KAuth
0002
0003 Execute actions as privileged user
0004
0005 ## Introduction
0006
0007 KAuth provides a convenient, system-integrated way to offload actions that need
0008 to be performed as a privileged user (root, for example) to small (hopefully
0009 secure) helper utilities.
0010
0011 ## Usage
0012
0013 If you are using CMake, you need to have
0014
0015     find_package(KF6Auth NO_MODULE)
0016
0017 (or find KF6 with the Auth component) in your CMakeLists.txt file. You need
0018 to link to KF6::AuthCore.
0019
0020 Executing privileged actions typically involves having a minimal helper utility
0021 that does the actual work, and calling that utility with escalated privileges if
0022 the user has permission to do so (often requiring the user to enter appropriate
0023 credentials, like entering a password).
0024
0025 Therefore, use of the KAuth library is in two parts.  In the main part of your
0026 code, you use KAuth::Action (and specifically KAuth::Action::execute()) when you
0027 need to do something privileged, like write to a file normally only writable by
0028 root.
0029
0030 The code that actually performs that action, such as writing to a file, needs to
0031 be placed in the slot of a helper QObject class, which should use the methods of
0032 KAuth::HelperSupport and be compiled into an executable.  You will also want to
0033 use the `kauth_install_helper_files` and `kauth_install_actions` macros in your
0034 CMakeLists.txt.
0035
0036 See <https://develop.kde.org/docs/features/kauth/> for a
0037 detailed tutorial on how to use KAuth.
0038