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

source code of kdesu/src/client.h