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 | |
28 | namespace 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 | |
48 | class KDESU_EXPORT KDEsuClient { |
49 | public: |
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 | |
190 | private: |
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 | |