1 |
NAME |
2 |
libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog |
3 |
handling |
4 |
|
5 |
SYNOPSIS |
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. |
42 |
|
43 |
DESCRIPTION |
44 |
Libptytty is a small library that offers pseudo-tty management in an |
45 |
OS-independent way. It was created out of frustration over the many |
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 |
252 |
|
253 |
BUGS |
254 |
You kiddin'? |
255 |
|
256 |
AUTHORS |
257 |
Emanuele Giaquinta <emanuele.giaquinta@gmail.com>, Marc Alexander |
258 |
Lehmann <rxvt-unicode@schmorp.de>. |
259 |
|