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 | |
21 | namespace 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 | */ |
48 | class KDESU_EXPORT Client |
49 | { |
50 | public: |
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 | |
215 | private: |
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 | |
221 | private: |
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 | |