1/*
2 This file is part of the KDE project, module kdesu.
3 SPDX-FileCopyrightText: 1999, 2000 Geert Jansen <jansen@kde.org>
4
5 SPDX-License-Identifier: GPL-2.0-only
6
7 client.h: client to access kdesud.
8*/
9
10#ifndef KDESUCLIENT_H
11#define KDESUCLIENT_H
12
13#include <kdesu/kdesu_export.h>
14
15#include <QByteArray>
16#include <QList>
17#include <memory>
18
19#ifdef Q_OS_UNIX
20
21namespace KDESu
22{
23/** \class Client client.h KDESu/Client
24 * A client class to access kdesud, the KDE su daemon. Kdesud can assist in
25 * password caching in two ways:
26 *
27 * @li For high security passwords, like for su and ssh, it executes the
28 * password requesting command for you. It feeds the password to the
29 * command, without ever returning it to you, the user.
30 * See exec, setPass, delCommand.
31 *
32 * @li For lower security passwords, like web and ftp passwords, it can act
33 * as a persistent storage for string variables. These variables are
34 * returned to the user.
35 * See setVar, delVar, delGroup.
36 *
37 * Porting from KF5 to KF6:
38 *
39 * The class KDESu::KDEsuClient was renamed to KDESu::Client.
40 *
41 * @since 6.0
42 */
43class KDESU_EXPORT Client
44{
45public:
46 Client();
47 ~Client();
48
49 Client(const Client &) = delete;
50 Client &operator=(const Client &) = delete;
51
52 /**
53 * Lets kdesud execute a command. If the daemon does not have a password
54 * for this command, this will fail and you need to call setPass().
55 *
56 * @param command The command to execute.
57 * @param user The user to run the command as.
58 * @param options Extra options.
59 * @param env Extra environment variables.
60 * @return Zero on success, -1 on failure.
61 */
62 int exec(const QByteArray &command, const QByteArray &user, const QByteArray &options = nullptr, const QList<QByteArray> &env = QList<QByteArray>());
63
64 /**
65 * Wait for the last command to exit and return the exit code.
66 * @return Exit code of last command, -1 on failure.
67 */
68 int exitCode();
69
70 /**
71 * Set root's password, lasts one session.
72 *
73 * @param pass Root's password.
74 * @param timeout The time that a password will live.
75 * @return Zero on success, -1 on failure.
76 */
77 int setPass(const char *pass, int timeout);
78
79 /**
80 * Set the target host (optional).
81 */
82 int setHost(const QByteArray &host);
83
84 /**
85 * Set the desired priority (optional), see StubProcess.
86 */
87 int setPriority(int priority);
88
89 /**
90 * Set the desired scheduler (optional), see StubProcess.
91 */
92 int setScheduler(int scheduler);
93
94 /**
95 * Remove a password for a user/command.
96 * @param command The command.
97 * @param user The user.
98 * @return zero on success, -1 on an error
99 */
100 int delCommand(const QByteArray &command, const QByteArray &user);
101
102 /**
103 * Set a persistent variable.
104 * @param key The name of the variable.
105 * @param value Its value.
106 * @param timeout The timeout in seconds for this key. Zero means
107 * no timeout.
108 * @param group Make the key part of a group. See delGroup.
109 * @return zero on success, -1 on failure.
110 */
111 int setVar(const QByteArray &key, const QByteArray &value, int timeout = 0, const QByteArray &group = nullptr);
112
113 /**
114 * Get a persistent variable.
115 * @param key The name of the variable.
116 * @return Its value.
117 */
118 QByteArray getVar(const QByteArray &key);
119
120 /**
121 * Gets all the keys that are membes of the given group.
122 * @param group the group name of the variables.
123 * @return a list of the keys in the group.
124 */
125 QList<QByteArray> getKeys(const QByteArray &group);
126
127 /**
128 * Returns true if the specified group exists is
129 * cached.
130 *
131 * @param group the group key
132 * @return true if the group is found
133 */
134 bool findGroup(const QByteArray &group);
135
136 /**
137 * Delete a persistent variable.
138 * @param key The name of the variable.
139 * @return zero on success, -1 on failure.
140 */
141 int delVar(const QByteArray &key);
142
143 /**
144 * Delete all persistent variables with the given key.
145 *
146 * A specicalized variant of delVar(QByteArray) that removes all
147 * subsets of the cached variables given by @p key. In order for all
148 * cached variables related to this key to be deleted properly, the
149 * value given to the @p group argument when the setVar function
150 * was called, must be a subset of the argument given here and the key
151 *
152 * @note Simply supplying the group key here WILL not necessarily
153 * work. If you only have a group key, then use delGroup instead.
154 *
155 * @param special_key the name of the variable.
156 * @return zero on success, -1 on failure.
157 */
158 int delVars(const QByteArray &special_key);
159
160 /**
161 * Delete all persistent variables in a group.
162 *
163 * @param group the group name. See setVar.
164 * @return
165 */
166 int delGroup(const QByteArray &group);
167
168 /**
169 * Ping kdesud. This can be used for diagnostics.
170 * @return Zero on success, -1 on failure
171 */
172 int ping();
173
174 /**
175 * Stop the daemon.
176 */
177 int stopServer();
178
179 /**
180 * Try to start up kdesud
181 */
182 int startServer();
183
184private:
185 KDESU_NO_EXPORT int connect();
186
187 KDESU_NO_EXPORT int command(const QByteArray &cmd, QByteArray *result = nullptr);
188 KDESU_NO_EXPORT QByteArray escape(const QByteArray &str);
189
190private:
191 std::unique_ptr<class ClientPrivate> const d;
192};
193
194} // END namespace KDESu
195
196#endif // Q_OS_UNIX
197
198#endif // KDESUCLIENT_H
199

source code of kdesu/src/client.h