File indexing completed on 2025-02-02 14:11:33
0001 /* 0002 This file is part of the KDE project, module kdesu. 0003 SPDX-FileCopyrightText: 1999, 2000 Geert Jansen <jansen@kde.org> 0004 0005 SPDX-License-Identifier: GPL-2.0-only 0006 0007 client.h: client to access kdesud. 0008 */ 0009 0010 #ifndef KDESUCLIENT_H 0011 #define KDESUCLIENT_H 0012 0013 #include <kdesu/kdesu_export.h> 0014 0015 #include <QByteArray> 0016 #include <QList> 0017 #include <memory> 0018 0019 #ifdef Q_OS_UNIX 0020 0021 namespace KDESu 0022 { 0023 /** \class KDEsuClient client.h KDESu/Client 0024 * A client class to access kdesud, the KDE su daemon. Kdesud can assist in 0025 * password caching in two ways: 0026 * 0027 * @li For high security passwords, like for su and ssh, it executes the 0028 * password requesting command for you. It feeds the password to the 0029 * command, without ever returning it to you, the user. 0030 * See exec, setPass, delCommand. 0031 * 0032 * @li For lower security passwords, like web and ftp passwords, it can act 0033 * as a persistent storage for string variables. These variables are 0034 * returned to the user. 0035 * See setVar, delVar, delGroup. 0036 */ 0037 0038 class KDESU_EXPORT KDEsuClient 0039 { 0040 public: 0041 KDEsuClient(); 0042 ~KDEsuClient(); 0043 0044 KDEsuClient(const KDEsuClient &) = delete; 0045 KDEsuClient &operator=(const KDEsuClient &) = delete; 0046 0047 /** 0048 * Lets kdesud execute a command. If the daemon does not have a password 0049 * for this command, this will fail and you need to call setPass(). 0050 * 0051 * @param command The command to execute. 0052 * @param user The user to run the command as. 0053 * @param options Extra options. 0054 * @param env Extra environment variables. 0055 * @return Zero on success, -1 on failure. 0056 */ 0057 int exec(const QByteArray &command, const QByteArray &user, const QByteArray &options = nullptr, const QList<QByteArray> &env = QList<QByteArray>()); 0058 0059 /** 0060 * Wait for the last command to exit and return the exit code. 0061 * @return Exit code of last command, -1 on failure. 0062 */ 0063 int exitCode(); 0064 0065 /** 0066 * Set root's password, lasts one session. 0067 * 0068 * @param pass Root's password. 0069 * @param timeout The time that a password will live. 0070 * @return Zero on success, -1 on failure. 0071 */ 0072 int setPass(const char *pass, int timeout); 0073 0074 /** 0075 * Set the target host (optional). 0076 */ 0077 int setHost(const QByteArray &host); 0078 0079 /** 0080 * Set the desired priority (optional), see StubProcess. 0081 */ 0082 int setPriority(int priority); 0083 0084 /** 0085 * Set the desired scheduler (optional), see StubProcess. 0086 */ 0087 int setScheduler(int scheduler); 0088 0089 /** 0090 * Remove a password for a user/command. 0091 * @param command The command. 0092 * @param user The user. 0093 * @return zero on success, -1 on an error 0094 */ 0095 int delCommand(const QByteArray &command, const QByteArray &user); 0096 0097 /** 0098 * Set a persistent variable. 0099 * @param key The name of the variable. 0100 * @param value Its value. 0101 * @param timeout The timeout in seconds for this key. Zero means 0102 * no timeout. 0103 * @param group Make the key part of a group. See delGroup. 0104 * @return zero on success, -1 on failure. 0105 */ 0106 int setVar(const QByteArray &key, const QByteArray &value, int timeout = 0, const QByteArray &group = nullptr); 0107 0108 /** 0109 * Get a persistent variable. 0110 * @param key The name of the variable. 0111 * @return Its value. 0112 */ 0113 QByteArray getVar(const QByteArray &key); 0114 0115 /** 0116 * Gets all the keys that are membes of the given group. 0117 * @param group the group name of the variables. 0118 * @return a list of the keys in the group. 0119 */ 0120 QList<QByteArray> getKeys(const QByteArray &group); 0121 0122 /** 0123 * Returns true if the specified group exists is 0124 * cached. 0125 * 0126 * @param group the group key 0127 * @return true if the group is found 0128 */ 0129 bool findGroup(const QByteArray &group); 0130 0131 /** 0132 * Delete a persistent variable. 0133 * @param key The name of the variable. 0134 * @return zero on success, -1 on failure. 0135 */ 0136 int delVar(const QByteArray &key); 0137 0138 /** 0139 * Delete all persistent variables with the given key. 0140 * 0141 * A specicalized variant of delVar(QByteArray) that removes all 0142 * subsets of the cached variables given by @p key. In order for all 0143 * cached variables related to this key to be deleted properly, the 0144 * value given to the @p group argument when the setVar function 0145 * was called, must be a subset of the argument given here and the key 0146 * 0147 * @note Simply supplying the group key here WILL not necessarily 0148 * work. If you only have a group key, then use delGroup instead. 0149 * 0150 * @param special_key the name of the variable. 0151 * @return zero on success, -1 on failure. 0152 */ 0153 int delVars(const QByteArray &special_key); 0154 0155 /** 0156 * Delete all persistent variables in a group. 0157 * 0158 * @param group the group name. See setVar. 0159 * @return 0160 */ 0161 int delGroup(const QByteArray &group); 0162 0163 /** 0164 * Ping kdesud. This can be used for diagnostics. 0165 * @return Zero on success, -1 on failure 0166 */ 0167 int ping(); 0168 0169 /** 0170 * Stop the daemon. 0171 */ 0172 int stopServer(); 0173 0174 /** 0175 * Try to start up kdesud 0176 */ 0177 int startServer(); 0178 0179 #if KDESU_ENABLE_DEPRECATED_SINCE(5, 99) 0180 /** 0181 * The server used to rely on being installed with an sgid bit to 0182 * prevent core dumps, ptrace and similar. This has been changed, and 0183 * the same security guarantees now apply even without the sgid bit, 0184 * so since 5.99 this always returns true. 0185 * 0186 * If calling code depends on KDESu 5.99 or newer already, use of this 0187 * can be dropped. With an older version of KDESu, then this should be 0188 * called to determine whether the server is usable. 0189 */ 0190 KDESU_DEPRECATED_VERSION(5, 99, "SGID no longer relevant since 5.99") 0191 bool isServerSGID(); 0192 #endif 0193 0194 private: 0195 KDESU_NO_EXPORT int connect(); 0196 0197 KDESU_NO_EXPORT int command(const QByteArray &cmd, QByteArray *result = nullptr); 0198 KDESU_NO_EXPORT QByteArray escape(const QByteArray &str); 0199 0200 private: 0201 std::unique_ptr<class KDEsuClientPrivate> const d; 0202 }; 0203 0204 } // END namespace KDESu 0205 0206 #endif // Q_OS_UNIX 0207 0208 #endif // KDESUCLIENT_H