kdesu/client.h

   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__