KDESu

client.h
1 /*
2  This file is part of the KDE project, module kdesu.
3  SPDX-FileCopyrightText: 1999, 2000 Geert Jansen <[email protected]>
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 /** \class KDEsuClient 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. The daemon should
30  * be installed setgid nogroup, in order to be able to act as an inaccessible,
31  * trusted 3rd party.
32  * See exec, setPass, delCommand.
33  *
34  * @li For lower security passwords, like web and ftp passwords, it can act
35  * as a persistent storage for string variables. These variables are
36  * returned to the user, and the daemon doesn't need to be setgid nogroup
37  * for this.
38  * See setVar, delVar, delGroup.
39  */
40 
41 class KDESU_EXPORT KDEsuClient
42 {
43 public:
44  KDEsuClient();
45  ~KDEsuClient();
46 
47  KDEsuClient(const KDEsuClient &) = delete;
48  KDEsuClient &operator=(const KDEsuClient &) = delete;
49 
50  /**
51  * Lets kdesud execute a command. If the daemon does not have a password
52  * for this command, this will fail and you need to call setPass().
53  *
54  * @param command The command to execute.
55  * @param user The user to run the command as.
56  * @param options Extra options.
57  * @param env Extra environment variables.
58  * @return Zero on success, -1 on failure.
59  */
60  int exec(const QByteArray &command, const QByteArray &user, const QByteArray &options = nullptr, const QList<QByteArray> &env = QList<QByteArray>());
61 
62  /**
63  * Wait for the last command to exit and return the exit code.
64  * @return Exit code of last command, -1 on failure.
65  */
66  int exitCode();
67 
68  /**
69  * Set root's password, lasts one session.
70  *
71  * @param pass Root's password.
72  * @param timeout The time that a password will live.
73  * @return Zero on success, -1 on failure.
74  */
75  int setPass(const char *pass, int timeout);
76 
77  /**
78  * Set the target host (optional).
79  */
80  int setHost(const QByteArray &host);
81 
82  /**
83  * Set the desired priority (optional), see StubProcess.
84  */
85  int setPriority(int priority);
86 
87  /**
88  * Set the desired scheduler (optional), see StubProcess.
89  */
90  int setScheduler(int scheduler);
91 
92  /**
93  * Remove a password for a user/command.
94  * @param command The command.
95  * @param user The user.
96  * @return zero on success, -1 on an error
97  */
98  int delCommand(const QByteArray &command, const QByteArray &user);
99 
100  /**
101  * Set a persistent variable.
102  * @param key The name of the variable.
103  * @param value Its value.
104  * @param timeout The timeout in seconds for this key. Zero means
105  * no timeout.
106  * @param group Make the key part of a group. See delGroup.
107  * @return zero on success, -1 on failure.
108  */
109  int setVar(const QByteArray &key, const QByteArray &value, int timeout = 0, const QByteArray &group = nullptr);
110 
111  /**
112  * Get a persistent variable.
113  * @param key The name of the variable.
114  * @return Its value.
115  */
116  QByteArray getVar(const QByteArray &key);
117 
118  /**
119  * Gets all the keys that are membes of the given group.
120  * @param group the group name of the variables.
121  * @return a list of the keys in the group.
122  */
123  QList<QByteArray> getKeys(const QByteArray &group);
124 
125  /**
126  * Returns true if the specified group exists is
127  * cached.
128  *
129  * @param group the group key
130  * @return true if the group is found
131  */
132  bool findGroup(const QByteArray &group);
133 
134  /**
135  * Delete a persistent variable.
136  * @param key The name of the variable.
137  * @return zero on success, -1 on failure.
138  */
139  int delVar(const QByteArray &key);
140 
141  /**
142  * Delete all persistent variables with the given key.
143  *
144  * A specicalized variant of delVar(QByteArray) that removes all
145  * subsets of the cached variables given by @p key. In order for all
146  * cached variables related to this key to be deleted properly, the
147  * value given to the @p group argument when the setVar function
148  * was called, must be a subset of the argument given here and the key
149  *
150  * @note Simply supplying the group key here WILL not necessarily
151  * work. If you only have a group key, then use delGroup instead.
152  *
153  * @param special_key the name of the variable.
154  * @return zero on success, -1 on failure.
155  */
156  int delVars(const QByteArray &special_key);
157 
158  /**
159  * Delete all persistent variables in a group.
160  *
161  * @param group the group name. See setVar.
162  * @return
163  */
164  int delGroup(const QByteArray &group);
165 
166  /**
167  * Ping kdesud. This can be used for diagnostics.
168  * @return Zero on success, -1 on failure
169  */
170  int ping();
171 
172  /**
173  * Stop the daemon.
174  */
175  int stopServer();
176 
177  /**
178  * Try to start up kdesud
179  */
180  int startServer();
181 
182  /**
183  * Returns true if the server is safe (installed setgid), false otherwise.
184  */
185  bool isServerSGID();
186 
187 private:
188  int connect();
189 
190  int command(const QByteArray &cmd, QByteArray *result = nullptr);
191  QByteArray escape(const QByteArray &str);
192 
193 private:
194  std::unique_ptr<class KDEsuClientPrivate> const d;
195 };
196 
197 } // END namespace KDESu
198 
199 #endif // Q_OS_UNIX
200 
201 #endif // KDESUCLIENT_H
QString escape(const QString &plain)
void setHost(ScriptableExtension *host)
ScriptableExtension * host() const
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sun Jun 26 2022 03:48:58 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.