1 | NAME |
1 | NAME |
2 | libptytty - 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 | -lptytty |
6 | cc ... -lptytty |
|
|
7 | |
|
|
8 | #include <libptytty.h> |
|
|
9 | |
|
|
10 | // C++ |
|
|
11 | ptytty *pty = ptytty::create (); |
|
|
12 | |
|
|
13 | if (!pty->get ()) |
|
|
14 | // error allocating pty |
|
|
15 | |
|
|
16 | if (we want utmp) |
|
|
17 | pty->login (process_pid, 0, "remote.host"); |
|
|
18 | else if (we want utmp AND wtmp/lastlog) |
|
|
19 | pty->login (process_pid, 1, "remote.host"); |
|
|
20 | |
|
|
21 | // we are done with it |
|
|
22 | delete pty; |
|
|
23 | |
|
|
24 | // C |
|
|
25 | PTYTTY pty = ptytty_create (); |
|
|
26 | |
|
|
27 | if (!ptytty_get (pty)) |
|
|
28 | // error allocating pty |
|
|
29 | |
|
|
30 | if (we want utmp) |
|
|
31 | ptytty_login (pty, process_pid, 0, "remote.host"); |
|
|
32 | else if (we want utmp AND wtmp/lastlog) |
|
|
33 | ptytty_login (pty, process_pid, 1, "remote.host"); |
|
|
34 | |
|
|
35 | // we are done with it |
|
|
36 | ptytty_delete (pty); |
|
|
37 | |
|
|
38 | See also the eg/ directory, which currently contains the c-sample.c file |
|
|
39 | that spawns a loginshell from C using libptytty. |
7 | |
40 | |
8 | DESCRIPTION |
41 | DESCRIPTION |
9 | TODO |
42 | Libptytty is a small library that offers pseudo-tty management in an |
|
|
43 | OS-independent way. It was created out of frustration over the many |
|
|
44 | differences of pty/tty handling in different operating systems for the |
|
|
45 | use inside "rxvt-unicode". |
|
|
46 | |
|
|
47 | In addition to offering mere pty/tty management, it also offers session |
|
|
48 | database support (utmp and optional wtmp/lastlog updates for login |
|
|
49 | shells). |
|
|
50 | |
|
|
51 | It also supports fork'ing after startup and dropping privileges in the |
|
|
52 | calling process, so in case the calling process gets compromised by the |
|
|
53 | user starting the program there is less to gain, as only the helper |
|
|
54 | process runs with privileges (e.g. setuid/setgid), which reduces the |
|
|
55 | area of attack immensely. |
|
|
56 | |
|
|
57 | Libptytty is written in C++, but it also offers a C-only API. |
10 | |
58 | |
11 | SECURITY CONSIDERATIONS |
59 | SECURITY CONSIDERATIONS |
12 | *It is of paramount importance that you at least read the following |
60 | *It is of paramount importance that you at least read the following |
13 | paragraph!* |
61 | paragraph!* |
14 | |
62 | |
… | |
… | |
23 | // in C: ptytty_init (); |
71 | // in C: ptytty_init (); |
24 | |
72 | |
25 | // initialise, parse arguments, etc. |
73 | // initialise, parse arguments, etc. |
26 | } |
74 | } |
27 | |
75 | |
28 | This checks wether the program runs setuid or setgid. If yes then it |
76 | This checks whether the program runs setuid or setgid. If yes then it |
29 | will fork a helper process and drop privileges. |
77 | will fork a helper process and drop privileges. |
30 | |
78 | |
31 | Some programs need finer control over if and when this helper process is |
79 | Some programs need finer control over if and when this helper process is |
32 | started, and if and how to drop privileges. For those programs, the |
80 | started, and if and how to drop privileges. For those programs, the |
33 | methods "ptytty::use_helper" and "ptytty::drop_privileges" are more |
81 | methods "ptytty::use_helper" and "ptytty::drop_privileges" are more |
… | |
… | |
38 | ptytty::init () |
86 | ptytty::init () |
39 | The default way to initialise libptytty. Must be called imemdiately |
87 | The default way to initialise libptytty. Must be called imemdiately |
40 | as the first thing in the "main" function, or earlier e.g. during |
88 | as the first thing in the "main" function, or earlier e.g. during |
41 | static construction time. The earlier, the better. |
89 | static construction time. The earlier, the better. |
42 | |
90 | |
43 | This method checks wether the program runs with setuid/setgid |
91 | This method checks whether the program runs with setuid/setgid |
44 | permissions and, if yes, spawns a helper process for pty/tty |
92 | permissions and, if yes, spawns a helper process for pty/tty |
45 | management. IT then drops the privileges completely, so the actual |
93 | management. It then drops the privileges completely, so the actual |
46 | program runs without setuid/setgid privileges. |
94 | program runs without setuid/setgid privileges. |
47 | |
95 | |
48 | ptytty::use_helper () |
96 | ptytty::use_helper () |
49 | Tries to start a helper process that retains privileges even when |
97 | Tries to start a helper process that retains privileges even when |
50 | the calling process does not. This is usually called from |
98 | the calling process does not. This is usually called from |
… | |
… | |
53 | privileges at startup, or when you are not running setuid/setgid but |
101 | privileges at startup, or when you are not running setuid/setgid but |
54 | want to drop privileges (e.g. when running as a root-started |
102 | want to drop privileges (e.g. when running as a root-started |
55 | daemon). |
103 | daemon). |
56 | |
104 | |
57 | This method will try not to start more than one helper process. The |
105 | This method will try not to start more than one helper process. The |
58 | same helper process cna usually be used form the process starting it |
106 | same helper process can usually be used both from the process |
59 | an all its fork'ed (not exec'ed) children |
107 | starting it and all its fork'ed (not exec'ed) children. |
60 | |
108 | |
61 | ptytty::drop_privileges () |
109 | ptytty::drop_privileges () |
62 | Drops privileges completely, i.e. sets real, effective and saved |
110 | Drops privileges completely, i.e. sets real, effective and saved |
63 | user id to the real user id. Also aborts if this cnanot be achieved. |
111 | user id to the real user id. Also aborts if this cannot be achieved. |
64 | Useful to make sure that the process doesn't run with special |
112 | Useful to make sure that the process doesn't run with special |
65 | privileges. |
113 | privileges. |
66 | |
114 | |
67 | bool success = ptytty::send_fd (int socket, int fd) |
115 | bool success = ptytty::send_fd (int socket, int fd) |
68 | Utility method to send a file descriptor over a unix domain socket. |
116 | Utility method to send a file descriptor over a unix domain socket. |
… | |
… | |
95 | "true" when successful. |
143 | "true" when successful. |
96 | |
144 | |
97 | pty->login (int cmd_pid, bool login_shell, const char *hostname) |
145 | pty->login (int cmd_pid, bool login_shell, const char *hostname) |
98 | Creates an entry in the systems session database(s) (utmp, wtmp, |
146 | Creates an entry in the systems session database(s) (utmp, wtmp, |
99 | lastlog). "cmd_pid" must be the pid of the process representing the |
147 | lastlog). "cmd_pid" must be the pid of the process representing the |
100 | session (such as the login shell), "login_shell" defines wether the |
148 | session (such as the login shell), "login_shell" defines whether the |
101 | session is associated with a login, which influences wether wtmp and |
149 | session is associated with a login, which influences whether wtmp and |
102 | lastlog entries are created, and "hostname" should identify the |
150 | lastlog entries are created, and "hostname" should identify the |
103 | "hostname" the user logs in from, which often is the value of the |
151 | "hostname" the user logs in from, which often is the value of the |
104 | "DISPLAY" variable or tty line in case of local logins. |
152 | "DISPLAY" variable or tty line in case of local logins. |
105 | |
153 | |
106 | Calling this method is optional. A session starts at the time of the |
154 | Calling this method is optional. A session starts at the time of the |
… | |
… | |
113 | Tries to make the pty/tty pair the controlling terminal of the |
161 | Tries to make the pty/tty pair the controlling terminal of the |
114 | current process. Useful after forking in the child/tty process. |
162 | current process. Useful after forking in the child/tty process. |
115 | |
163 | |
116 | pty->set_utf8_mode (bool on) |
164 | pty->set_utf8_mode (bool on) |
117 | On systems supporting special UTF-8 line disciplines (e.g. Linux), |
165 | On systems supporting special UTF-8 line disciplines (e.g. Linux), |
118 | tries to enable it for the given pty. Can be called at any time to |
166 | this tries to enable this discipline for the given pty. Can be |
119 | change the mode. |
167 | called at any time to change the mode. |
120 | |
168 | |
121 | C INTERFACE: THE ptytty FAMILY OF FUNCTIONS |
169 | C INTERFACE: THE ptytty FAMILY OF FUNCTIONS |
122 | ptytty_init () |
170 | ptytty_init () |
123 | See "ptytty::init ()". |
171 | See "ptytty::init ()". |
124 | |
172 | |
125 | PTYTTY ptytty_create () |
173 | PTYTTY ptytty_create () |
126 | Creates a new opaque PTYTTY object and returns it. Do not try to |
174 | Creates a new opaque PTYTTY object and returns it. Do not try to |
127 | access it in any way excecp by testing it for truthness (e.g. "if |
175 | access it in any way except by testing it for truthness (e.g. "if |
128 | (pty) ...."). See "ptytty::create ()". |
176 | (pty) ...."). See "ptytty::create ()". |
129 | |
177 | |
130 | int ptytty_pty (PTYTTY ptytty) |
178 | int ptytty_pty (PTYTTY ptytty) |
131 | Return the pty file descriptor. See "pty->pty". |
179 | Return the pty file descriptor. See "pty->pty". |
132 | |
180 | |