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