… | |
… | |
4 | |
4 | |
5 | SYNOPSIS |
5 | SYNOPSIS |
6 | cc ... -lptytty |
6 | cc ... -lptytty |
7 | |
7 | |
8 | #include <libptytty.h> |
8 | #include <libptytty.h> |
|
|
9 | |
9 | |
10 | |
10 | // C++ |
11 | // C++ |
11 | ptytty *pty = ptytty::create (); |
12 | ptytty *pty = ptytty::create (); |
12 | |
13 | |
13 | if (!pty->get ()) |
14 | if (!pty->get ()) |
… | |
… | |
19 | pty->login (process_pid, 1, "remote.host"); |
20 | pty->login (process_pid, 1, "remote.host"); |
20 | |
21 | |
21 | // we are done with it |
22 | // we are done with it |
22 | delete pty; |
23 | delete pty; |
23 | |
24 | |
|
|
25 | |
24 | // C |
26 | // C |
25 | PTYTTY pty = ptytty_create (); |
27 | PTYTTY pty = ptytty_create (); |
26 | |
28 | |
27 | if (!ptytty_get (pty)) |
29 | if (!ptytty_get (pty)) |
28 | // error allocating pty |
30 | // error allocating pty |
… | |
… | |
34 | |
36 | |
35 | // we are done with it |
37 | // we are done with it |
36 | ptytty_delete (pty); |
38 | ptytty_delete (pty); |
37 | |
39 | |
38 | See also the eg/ directory, which currently contains the c-sample.c file |
40 | See also the eg/ directory, which currently contains the c-sample.c file |
39 | that spawns a loginshell from C using libptytty. |
41 | that spawns a login shell from C using libptytty. |
40 | |
42 | |
41 | DESCRIPTION |
43 | DESCRIPTION |
42 | Libptytty is a small library that offers pseudo-tty management in an |
44 | 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 |
45 | OS-independent way. It was created out of frustration over the many |
44 | differences of pty/tty handling in different operating systems for the |
46 | differences of pty/tty handling in different operating systems for the |
… | |
… | |
58 | |
60 | |
59 | SECURITY CONSIDERATIONS |
61 | SECURITY CONSIDERATIONS |
60 | *It is of paramount importance that you at least read the following |
62 | *It is of paramount importance that you at least read the following |
61 | paragraph!* |
63 | paragraph!* |
62 | |
64 | |
63 | If you are a typical terminal-like program that just wants one or more |
65 | If you write a typical terminal-like program that just wants one or more |
64 | ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" |
66 | ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" |
65 | function) as the very first thing in your program: |
67 | function) as the very first thing in your program: |
66 | |
68 | |
67 | int main (int argc, char *argv[]) |
69 | int main (int argc, char *argv[]) |
68 | { |
70 | { |
… | |
… | |
76 | This checks whether the program runs setuid or setgid. If yes then it |
78 | This checks whether the program runs setuid or setgid. If yes then it |
77 | will fork a helper process and drop privileges. |
79 | will fork a helper process and drop privileges. |
78 | |
80 | |
79 | Some programs need finer control over if and when this helper process is |
81 | Some programs need finer control over if and when this helper process is |
80 | started, and if and how to drop privileges. For those programs, the |
82 | started, and if and how to drop privileges. For those programs, the |
81 | methods "ptytty::use_helper" and "ptytty::drop_privileges" are more |
83 | methods "ptytty::use_helper" and "ptytty::drop_privileges" (and possibly |
82 | useful. |
84 | "ptytty::sanitise_stdfd") are more useful. |
83 | |
85 | |
84 | C++ INTERFACE: THE ptytty CLASS |
86 | C++ INTERFACE: THE ptytty CLASS |
85 | STATIC METHODS |
87 | STATIC METHODS |
86 | ptytty::init () |
88 | ptytty::init () |
87 | The default way to initialise libptytty. Must be called imemdiately |
89 | The default way to initialise libptytty. Must be called immediately |
88 | as the first thing in the "main" function, or earlier e.g. during |
90 | as the first thing in the "main" function, or earlier e.g. during |
89 | static construction time. The earlier, the better. |
91 | static construction time. The earlier, the better. |
90 | |
92 | |
91 | This method checks whether the program runs with setuid/setgid |
93 | This method calls "sanitise_stdfd" and then checks whether the |
92 | permissions and, if yes, spawns a helper process for pty/tty |
94 | program runs with setuid/setgid permissions and, if yes, spawns a |
93 | management. It then drops the privileges completely, so the actual |
95 | helper process for pty/tty management. It then drops the privileges |
94 | program runs without setuid/setgid privileges. |
96 | completely, so the actual program runs without setuid/setgid |
|
|
97 | privileges. |
95 | |
98 | |
96 | ptytty::use_helper () |
99 | ptytty::use_helper () |
97 | Tries to start a helper process that retains privileges even when |
100 | Tries to start a helper process that retains privileges even when |
98 | the calling process does not. This is usually called from |
101 | the calling process does not. This is usually called from |
99 | "ptytty::init" when it detects that the program is running setuid or |
102 | "ptytty::init" when it detects that the program is running setuid or |
100 | setgid, but can be called manually if it is inconvinient to drop |
103 | setgid, but can be called manually if it is inconvenient to drop |
101 | privileges at startup, or when you are not running setuid/setgid but |
104 | privileges at startup, or when you are not running setuid/setgid but |
102 | want to drop privileges (e.g. when running as a root-started |
105 | want to drop privileges (e.g. when running as a root-started |
103 | daemon). |
106 | daemon). |
104 | |
107 | |
105 | This method will try not to start more than one helper process. The |
108 | This method will try not to start more than one helper process. The |
… | |
… | |
110 | Drops privileges completely, i.e. sets real, effective and saved |
113 | Drops privileges completely, i.e. sets real, effective and saved |
111 | user id to the real user id. Also aborts if this cannot be achieved. |
114 | user id to the real user id. Also aborts if this cannot be achieved. |
112 | Useful to make sure that the process doesn't run with special |
115 | Useful to make sure that the process doesn't run with special |
113 | privileges. |
116 | privileges. |
114 | |
117 | |
|
|
118 | ptytty::sanitise_stdfd () |
|
|
119 | 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 |
|
|
121 | /dev/null if possible (and aborts otherwise). This is necessary |
|
|
122 | because libptytty might want to output error messages to those |
|
|
123 | descriptors, which at the time of outputting the error message, |
|
|
124 | might be connected to something unsuitable opened by the |
|
|
125 | unsuspecting program itself (this can be a security issue). |
|
|
126 | |
115 | bool success = ptytty::send_fd (int socket, int fd) |
127 | bool success = ptytty::send_fd (int socket, int fd) |
116 | Utility method to send a file descriptor over a unix domain socket. |
128 | Utility method to send a file descriptor over a unix domain socket. |
117 | Returns true if successful, false otherwise. This method is only |
129 | Returns true if successful, false otherwise. This method is only |
118 | exposed for your convinience and is not required for normal |
130 | exposed for your convenience and is not required for normal |
119 | operation. |
131 | operation. |
120 | |
132 | |
121 | int fd = ptytty::recv_fd (int socket) |
133 | int fd = ptytty::recv_fd (int socket) |
122 | Utility method to receive a file descriptor over a unix domain |
134 | Utility method to receive a file descriptor over a unix domain |
123 | socket. Returns the fd if sucecssful and -1 otherwise. This method |
135 | socket. Returns the fd if successful and -1 otherwise. This method |
124 | is only exposed for your convinience and is not required for normal |
136 | is only exposed for your convenience and is not required for normal |
125 | operation. |
137 | operation. |
126 | |
138 | |
127 | ptytty *pty = ptytty::create () |
139 | ptytty *pty = ptytty::create () |
128 | Creates new ptytty object. Creation does not yet do anything besides |
140 | Creates new ptytty object. Creation does not yet do anything besides |
129 | allocating the structure. |
141 | allocating the structure. |
… | |
… | |
144 | |
156 | |
145 | pty->login (int cmd_pid, bool login_shell, const char *hostname) |
157 | pty->login (int cmd_pid, bool login_shell, const char *hostname) |
146 | Creates an entry in the systems session database(s) (utmp, wtmp, |
158 | Creates an entry in the systems session database(s) (utmp, wtmp, |
147 | lastlog). "cmd_pid" must be the pid of the process representing the |
159 | lastlog). "cmd_pid" must be the pid of the process representing the |
148 | session (such as the login shell), "login_shell" defines whether the |
160 | session (such as the login shell), "login_shell" defines whether the |
149 | session is associated with a login, which influences whether wtmp and |
161 | session is associated with a login, which influences whether wtmp |
150 | lastlog entries are created, and "hostname" should identify the |
162 | and lastlog entries are created, and "hostname" should identify the |
151 | "hostname" the user logs in from, which often is the value of the |
163 | "hostname" the user logs in from, which often is the value of the |
152 | "DISPLAY" variable or tty line in case of local logins. |
164 | "DISPLAY" variable or tty line in case of local logins. |
153 | |
165 | |
154 | Calling this method is optional. A session starts at the time of the |
166 | Calling this method is optional. A session starts at the time of the |
155 | login call and extends until the ptytty object is destroyed. |
167 | login call and extends until the ptytty object is destroyed. |