ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libptytty/README
(Generate patch)

Comparing libptytty/README (file contents):
Revision 1.7 by sf-exg, Wed Dec 21 00:48:52 2011 UTC vs.
Revision 1.11 by sf-exg, Tue Jul 27 08:43:41 2021 UTC

… …
55 user starting the program there is less to gain, as only the helper 55 user starting the program there is less to gain, as only the helper
56 process runs with privileges (e.g. setuid/setgid), which reduces the 56 process runs with privileges (e.g. setuid/setgid), which reduces the
57 area of attack immensely. 57 area of attack immensely.
58 58
59 Libptytty is written in C++, but it also offers a C-only API. 59 Libptytty is written in C++, but it also offers a C-only API.
60
61INSTALLATION
62 libptytty uses "CMake" as build system. To build libptytty, install
63 "CMake" and run the following commands from either the libptytty source
64 directory or a separate build directory:
65
66 cmake -DCMAKE_INSTALL_PREFIX=<prefix> -DBUILD_SHARED_LIBS=ON <path/to/libptytty>
67 cmake --build .
68 cmake --install .
60 69
61SECURITY CONSIDERATIONS 70SECURITY CONSIDERATIONS
62 *It is of paramount importance that you at least read the following 71 *It is of paramount importance that you at least read the following
63 paragraph!* 72 paragraph!*
64 73
… …
93 This method calls "sanitise_stdfd" and then checks whether the 102 This method calls "sanitise_stdfd" and then checks whether the
94 program runs with setuid/setgid permissions and, if yes, spawns a 103 program runs with setuid/setgid permissions and, if yes, spawns a
95 helper process for pty/tty management. It then drops the privileges 104 helper process for pty/tty management. It then drops the privileges
96 completely, so the actual program runs without setuid/setgid 105 completely, so the actual program runs without setuid/setgid
97 privileges. 106 privileges.
107
108 On failure, this method throws a "ptytty_error" exception.
98 109
99 ptytty::use_helper () 110 ptytty::use_helper ()
100 Tries to start a helper process that retains privileges even when 111 Tries to start a helper process that retains privileges even when
101 the calling process does not. This is usually called from 112 the calling process does not. This is usually called from
102 "ptytty::init" when it detects that the program is running setuid or 113 "ptytty::init" when it detects that the program is running setuid or
… …
107 118
108 This method will try not to start more than one helper process. The 119 This method will try not to start more than one helper process. The
109 same helper process can usually be used both from the process 120 same helper process can usually be used both from the process
110 starting it and all its fork'ed (not exec'ed) children. 121 starting it and all its fork'ed (not exec'ed) children.
111 122
123 On failure, this method throws a "ptytty_error" exception.
124
112 ptytty::drop_privileges () 125 ptytty::drop_privileges ()
113 Drops privileges completely, i.e. sets real, effective and saved 126 Drops privileges completely, i.e. sets real, effective and saved
114 user id to the real user id. Also aborts if this cannot be achieved. 127 user id to the real user id. Useful to make sure that the process
115 Useful to make sure that the process doesn't run with special 128 doesn't run with special privileges.
116 privileges. 129
130 On failure, this method throws a "ptytty_error" exception.
117 131
118 ptytty::sanitise_stdfd () 132 ptytty::sanitise_stdfd ()
119 Checks whether file descriptors 0, 1 and 2 (stdin, stdout and 133 Checks whether file descriptors 0, 1 and 2 (stdin, stdout and
120 stderr) are valid (open) and, if not, connects them to /dev/tty or 134 stderr) are valid (open) and, if not, connects them to /dev/tty or
121 /dev/null if possible (and aborts otherwise). This is necessary 135 /dev/null if possible. This is necessary because libptytty might
122 because libptytty might want to output error messages to those 136 want to output error messages to those descriptors, which at the
123 descriptors, which at the time of outputting the error message, 137 time of outputting the error message, might be connected to
124 might be connected to something unsuitable opened by the 138 something unsuitable opened by the unsuspecting program itself (this
125 unsuspecting program itself (this can be a security issue). 139 can be a security issue).
140
141 On failure, this method throws a "ptytty_error" exception.
126 142
127 bool success = ptytty::send_fd (int socket, int fd) 143 bool success = ptytty::send_fd (int socket, int fd)
128 Utility method to send a file descriptor over a unix domain socket. 144 Utility method to send a file descriptor over a unix domain socket.
129 Returns true if successful, false otherwise. This method is only 145 Returns true if successful, false otherwise. This method is only
130 exposed for your convenience and is not required for normal 146 exposed for your convenience and is not required for normal
… …
145 161
146 DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS 162 DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS
147 int pty_fd = pty->pty 163 int pty_fd = pty->pty
148 int tty_fd = pty->tty 164 int tty_fd = pty->tty
149 These members contain the pty and tty file descriptors, 165 These members contain the pty and tty file descriptors,
150 respectively. They initially contain -1 until a successful to 166 respectively. They initially contain -1 until a successful call to
151 "ptytty::get". 167 "ptytty::get".
152 168
153 bool success = pty->get () 169 bool success = pty->get ()
154 Tries to find, allocate and initialise a new pty/tty pair. Returns 170 Tries to find, allocate and initialise a new pty/tty pair. Returns
155 "true" when successful. 171 "true" when successful.
172
173 If the helper process is running and there is a protocol error, this
174 method throws a "ptytty_error" exception.
156 175
157 pty->login (int cmd_pid, bool login_shell, const char *hostname) 176 pty->login (int cmd_pid, bool login_shell, const char *hostname)
158 Creates an entry in the systems session database(s) (utmp, wtmp, 177 Creates an entry in the systems session database(s) (utmp, wtmp,
159 lastlog). "cmd_pid" must be the pid of the process representing the 178 lastlog). "cmd_pid" must be the pid of the process representing the
160 session (such as the login shell), "login_shell" defines whether the 179 session (such as the login shell), "login_shell" defines whether the
… …
218 See "ptytty::drop_privileges". 237 See "ptytty::drop_privileges".
219 238
220 void ptytty_use_helper () 239 void ptytty_use_helper ()
221 See "ptytty::use_helper". 240 See "ptytty::use_helper".
222 241
242PORTABILITY
243 To date, libptytty has been tested on the following platforms:
244
245 GNU/Linux
246 FreeBSD
247 NetBSD
248 OpenBSD
249 macOS
250 Solaris
251 AIX
252
223BUGS 253BUGS
224 You kiddin'? 254 You kiddin'?
225 255
226AUTHORS 256AUTHORS
227 Emanuele Giaquinta <e.giaquinta@glauco.it>, Marc Alexander Lehmann 257 Emanuele Giaquinta <emanuele.giaquinta@gmail.com>, Marc Alexander
228 <rxvt-unicode@schmorp.de>. 258 Lehmann <rxvt-unicode@schmorp.de>.
229 259

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines