1 | NAME |
1 | NAME |
2 | libpty - OS independent and secure pty/tty and utmp/wtmp/lastlog |
2 | libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog |
3 | handling |
3 | handling |
4 | |
4 | |
5 | SYNOPSIS |
5 | SYNOPSIS |
6 | -lpty |
6 | cc ... -lptytty |
|
|
7 | |
|
|
8 | #include <libptytty.h> |
|
|
9 | |
|
|
10 | |
|
|
11 | // C++ |
|
|
12 | ptytty *pty = ptytty::create (); |
|
|
13 | |
|
|
14 | if (!pty->get ()) |
|
|
15 | // error allocating pty |
|
|
16 | |
|
|
17 | if (we want utmp) |
|
|
18 | pty->login (process_pid, 0, "remote.host"); |
|
|
19 | else if (we want utmp AND wtmp/lastlog) |
|
|
20 | pty->login (process_pid, 1, "remote.host"); |
|
|
21 | |
|
|
22 | // we are done with it |
|
|
23 | delete pty; |
|
|
24 | |
|
|
25 | |
|
|
26 | // C |
|
|
27 | PTYTTY pty = ptytty_create (); |
|
|
28 | |
|
|
29 | if (!ptytty_get (pty)) |
|
|
30 | // error allocating pty |
|
|
31 | |
|
|
32 | if (we want utmp) |
|
|
33 | ptytty_login (pty, process_pid, 0, "remote.host"); |
|
|
34 | else if (we want utmp AND wtmp/lastlog) |
|
|
35 | ptytty_login (pty, process_pid, 1, "remote.host"); |
|
|
36 | |
|
|
37 | // we are done with it |
|
|
38 | ptytty_delete (pty); |
|
|
39 | |
|
|
40 | See also the eg/ directory, which currently contains the c-sample.c file |
|
|
41 | that spawns a login shell from C using libptytty. |
7 | |
42 | |
8 | DESCRIPTION |
43 | DESCRIPTION |
9 | THE pty CLASS |
44 | Libptytty is a small library that offers pseudo-tty management in an |
10 | new pty |
45 | OS-independent way. It was created out of frustration over the many |
11 | ... |
46 | differences of pty/tty handling in different operating systems for the |
|
|
47 | use inside "rxvt-unicode". |
|
|
48 | |
|
|
49 | In addition to offering mere pty/tty management, it also offers session |
|
|
50 | database support (utmp and optional wtmp/lastlog updates for login |
|
|
51 | shells). |
|
|
52 | |
|
|
53 | It also supports fork'ing after startup and dropping privileges in the |
|
|
54 | calling process, so in case the calling process gets compromised by the |
|
|
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 |
|
|
57 | area of attack immensely. |
|
|
58 | |
|
|
59 | Libptytty is written in C++, but it also offers a C-only API. |
|
|
60 | |
|
|
61 | INSTALLATION |
|
|
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 . |
|
|
69 | |
|
|
70 | SECURITY CONSIDERATIONS |
|
|
71 | *It is of paramount importance that you at least read the following |
|
|
72 | paragraph!* |
|
|
73 | |
|
|
74 | If you write a typical terminal-like program that just wants one or more |
|
|
75 | ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" |
|
|
76 | function) as the very first thing in your program: |
|
|
77 | |
|
|
78 | int main (int argc, char *argv[]) |
|
|
79 | { |
|
|
80 | // do nothing here |
|
|
81 | ptytty::init (); |
|
|
82 | // in C: ptytty_init (); |
|
|
83 | |
|
|
84 | // initialise, parse arguments, etc. |
|
|
85 | } |
|
|
86 | |
|
|
87 | This checks whether the program runs setuid or setgid. If yes then it |
|
|
88 | will fork a helper process and drop privileges. |
|
|
89 | |
|
|
90 | Some programs need finer control over if and when this helper process is |
|
|
91 | started, and if and how to drop privileges. For those programs, the |
|
|
92 | methods "ptytty::use_helper" and "ptytty::drop_privileges" (and possibly |
|
|
93 | "ptytty::sanitise_stdfd") are more useful. |
|
|
94 | |
|
|
95 | C++ INTERFACE: THE ptytty CLASS |
|
|
96 | STATIC METHODS |
|
|
97 | ptytty::init () |
|
|
98 | The default way to initialise libptytty. Must be called immediately |
|
|
99 | as the first thing in the "main" function, or earlier e.g. during |
|
|
100 | static construction time. The earlier, the better. |
|
|
101 | |
|
|
102 | This method calls "sanitise_stdfd" and then checks whether the |
|
|
103 | program runs with setuid/setgid permissions and, if yes, spawns a |
|
|
104 | helper process for pty/tty management. It then drops the privileges |
|
|
105 | completely, so the actual program runs without setuid/setgid |
|
|
106 | privileges. |
|
|
107 | |
|
|
108 | On failure, this method throws a "ptytty_error" exception. |
|
|
109 | |
|
|
110 | ptytty::use_helper () |
|
|
111 | Tries to start a helper process that retains privileges even when |
|
|
112 | the calling process does not. This is usually called from |
|
|
113 | "ptytty::init" when it detects that the program is running setuid or |
|
|
114 | setgid, but can be called manually if it is inconvenient to drop |
|
|
115 | privileges at startup, or when you are not running setuid/setgid but |
|
|
116 | want to drop privileges (e.g. when running as a root-started |
|
|
117 | daemon). |
|
|
118 | |
|
|
119 | This method will try not to start more than one helper process. The |
|
|
120 | same helper process can usually be used both from the process |
|
|
121 | starting it and all its fork'ed (not exec'ed) children. |
|
|
122 | |
|
|
123 | On failure, this method throws a "ptytty_error" exception. |
|
|
124 | |
|
|
125 | ptytty::drop_privileges () |
|
|
126 | Drops privileges completely, i.e. sets real, effective and saved |
|
|
127 | user id to the real user id. Useful to make sure that the process |
|
|
128 | doesn't run with special privileges. |
|
|
129 | |
|
|
130 | On failure, this method throws a "ptytty_error" exception. |
|
|
131 | |
|
|
132 | ptytty::sanitise_stdfd () |
|
|
133 | Checks whether file descriptors 0, 1 and 2 (stdin, stdout and |
|
|
134 | stderr) are valid (open) and, if not, connects them to /dev/tty or |
|
|
135 | /dev/null if possible. This is necessary because libptytty might |
|
|
136 | want to output error messages to those descriptors, which at the |
|
|
137 | time of outputting the error message, might be connected to |
|
|
138 | something unsuitable opened by the unsuspecting program itself (this |
|
|
139 | can be a security issue). |
|
|
140 | |
|
|
141 | On failure, this method throws a "ptytty_error" exception. |
|
|
142 | |
|
|
143 | bool success = ptytty::send_fd (int socket, int fd) |
|
|
144 | Utility method to send a file descriptor over a unix domain socket. |
|
|
145 | Returns true if successful, false otherwise. This method is only |
|
|
146 | exposed for your convenience and is not required for normal |
|
|
147 | operation. |
|
|
148 | |
|
|
149 | int fd = ptytty::recv_fd (int socket) |
|
|
150 | Utility method to receive a file descriptor over a unix domain |
|
|
151 | socket. Returns the fd if successful and -1 otherwise. This method |
|
|
152 | is only exposed for your convenience and is not required for normal |
|
|
153 | operation. |
|
|
154 | |
|
|
155 | ptytty *pty = ptytty::create () |
|
|
156 | Creates new ptytty object. Creation does not yet do anything besides |
|
|
157 | allocating the structure. |
|
|
158 | |
|
|
159 | A static method is used because the actual ptytty implementation can |
|
|
160 | differ at runtime, so you need a dynamic object creation facility. |
|
|
161 | |
|
|
162 | DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS |
|
|
163 | int pty_fd = pty->pty |
|
|
164 | int tty_fd = pty->tty |
|
|
165 | These members contain the pty and tty file descriptors, |
|
|
166 | respectively. They initially contain -1 until a successful call to |
|
|
167 | "ptytty::get". |
|
|
168 | |
|
|
169 | bool success = pty->get () |
|
|
170 | Tries to find, allocate and initialise a new pty/tty pair. Returns |
|
|
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. |
|
|
175 | |
|
|
176 | pty->login (int cmd_pid, bool login_shell, const char *hostname) |
|
|
177 | Creates an entry in the systems session database(s) (utmp, wtmp, |
|
|
178 | lastlog). "cmd_pid" must be the pid of the process representing the |
|
|
179 | session (such as the login shell), "login_shell" defines whether the |
|
|
180 | session is associated with a login, which influences whether wtmp |
|
|
181 | and lastlog entries are created, and "hostname" should identify the |
|
|
182 | "hostname" the user logs in from, which often is the value of the |
|
|
183 | "DISPLAY" variable or tty line in case of local logins. |
|
|
184 | |
|
|
185 | Calling this method is optional. A session starts at the time of the |
|
|
186 | login call and extends until the ptytty object is destroyed. |
|
|
187 | |
|
|
188 | pty->close_tty () |
|
|
189 | Closes the tty. Useful after forking in the parent/pty process. |
|
|
190 | |
|
|
191 | bool success = pty->make_controlling_tty () |
|
|
192 | Tries to make the pty/tty pair the controlling terminal of the |
|
|
193 | current process. Useful after forking in the child/tty process. |
|
|
194 | |
|
|
195 | pty->set_utf8_mode (bool on) |
|
|
196 | On systems supporting special UTF-8 line disciplines (e.g. Linux), |
|
|
197 | this tries to enable this discipline for the given pty. Can be |
|
|
198 | called at any time to change the mode. |
|
|
199 | |
|
|
200 | C INTERFACE: THE ptytty FAMILY OF FUNCTIONS |
|
|
201 | ptytty_init () |
|
|
202 | See "ptytty::init ()". |
|
|
203 | |
|
|
204 | PTYTTY ptytty_create () |
|
|
205 | Creates a new opaque PTYTTY object and returns it. Do not try to |
|
|
206 | access it in any way except by testing it for truthness (e.g. "if |
|
|
207 | (pty) ...."). See "ptytty::create ()". |
|
|
208 | |
|
|
209 | int ptytty_pty (PTYTTY ptytty) |
|
|
210 | Return the pty file descriptor. See "pty->pty". |
|
|
211 | |
|
|
212 | int ptytty_tty (PTYTTY ptytty) |
|
|
213 | Return the tty file descriptor. See "pty->tty". |
|
|
214 | |
|
|
215 | void ptytty_delete (PTYTTY ptytty) |
|
|
216 | Destroys the PTYTTY object, freeing the pty/tty pair and cleaning up |
|
|
217 | the utmp/wtmp/lastlog databases, if initialised/used. Same as |
|
|
218 | "delete pty" in C++. |
|
|
219 | |
|
|
220 | int ptytty_get (PTYTTY ptytty) |
|
|
221 | See "pty->get", returns 0 in case of an error, non-zero otherwise. |
|
|
222 | |
|
|
223 | void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const |
|
|
224 | char *hostname) |
|
|
225 | See "pty->login". |
|
|
226 | |
|
|
227 | void ptytty_close_tty (PTYTTY ptytty) |
|
|
228 | See "pty->close_tty". |
|
|
229 | |
|
|
230 | int ptytty_make_controlling_tty (PTYTTY ptytty) |
|
|
231 | See "pty->make_controlling_tty". |
|
|
232 | |
|
|
233 | void ptytty_set_utf8_mode (PTYTTY ptytty, int on) |
|
|
234 | See "pty->set_utf8_mode". |
|
|
235 | |
|
|
236 | void ptytty_drop_privileges () |
|
|
237 | See "ptytty::drop_privileges". |
|
|
238 | |
|
|
239 | void ptytty_use_helper () |
|
|
240 | See "ptytty::use_helper". |
|
|
241 | |
|
|
242 | PORTABILITY |
|
|
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 |
12 | |
252 | |
13 | BUGS |
253 | BUGS |
14 | You kiddin'? |
254 | You kiddin'? |
15 | |
255 | |
16 | AUTHORS |
256 | AUTHORS |
17 | Emanuele Giaquinta <e.giaquinta@glauco.it>, Marc Alexander Lehmann |
257 | Emanuele Giaquinta <emanuele.giaquinta@gmail.com>, Marc Alexander |
18 | <rxvt-unicode@schmorp.de>. |
258 | Lehmann <rxvt-unicode@schmorp.de>. |
19 | |
259 | |