1 | =head1 NAME |
1 | // This file is part of libptytty. Do not make local modifications. |
|
|
2 | // http://software.schmorp.de/pkg/libptytty |
2 | |
3 | |
3 | libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog handling |
4 | #ifndef LIBPTYTTY_H_ /* public libptytty header file */ |
|
|
5 | #define LIBPTYTTY_H_ |
4 | |
6 | |
5 | =head1 SYNOPSIS |
7 | #ifdef __cplusplus |
6 | |
8 | |
7 | -lptytty |
9 | // c++ api |
8 | |
10 | |
9 | =head1 DESCRIPTION |
11 | struct ptytty { |
|
|
12 | int pty; // pty file descriptor; connected to rxvt |
|
|
13 | int tty; // tty file descriptor; connected to child |
10 | |
14 | |
11 | TODO |
15 | virtual ~ptytty () |
|
|
16 | { |
|
|
17 | } |
12 | |
18 | |
13 | =head1 SECURITY CONSIDERATIONS |
19 | virtual bool get () = 0; |
|
|
20 | virtual void login (int cmd_pid, bool login_shell, const char *hostname) = 0; |
14 | |
21 | |
15 | I<< B<It is of paramount importance that you at least read the following |
22 | void close_tty (); |
16 | paragraph!> >> |
23 | bool make_controlling_tty (); |
|
|
24 | void set_utf8_mode (bool on); |
17 | |
25 | |
18 | If you are a typical terminal-like program that just wants one or more |
26 | static void init (); |
19 | ptys, you should call the C<ptytty::init ()> method (C: C<ptytty_init () |
27 | static ptytty *create (); // create a new pty object |
20 | function) as the very first thing in your program: |
|
|
21 | |
28 | |
22 | int main (int argc, char *argv[]) |
29 | static void drop_privileges (); |
23 | { |
30 | static void use_helper (); |
24 | // do nothing here |
|
|
25 | ptytty::init (); |
|
|
26 | // in C: ptytty_init (); |
|
|
27 | |
31 | |
28 | // initialise, parse arguments, etc. |
32 | static bool send_fd (int socket, int fd); |
29 | } |
33 | static int recv_fd (int socket); |
30 | |
34 | |
31 | This checks wether the program runs setuid or setgid. If yes then it will |
35 | protected: |
32 | fork a helper process and drop privileges. |
|
|
33 | |
36 | |
34 | Some programs need finer control over if and when this helper process |
37 | ptytty () |
35 | is started, and if and how to drop privileges. For those programs, the |
38 | : pty(-1), tty(-1) |
36 | methods C<ptytty::use_helper> and C<ptytty::drop_privileges> are more |
39 | { |
37 | useful. |
40 | } |
|
|
41 | }; |
38 | |
42 | |
39 | =head1 C++ INTERFACE: THE ptytty CLASS |
43 | #else |
40 | |
44 | |
41 | =head2 STATIC METHODS |
45 | // c api |
42 | |
46 | |
43 | =over 4 |
47 | typedef void *PTYTTY; |
44 | |
48 | |
45 | =item ptytty::init () |
49 | int ptytty_pty (PTYTTY ptytty); |
|
|
50 | int ptytty_tty (PTYTTY ptytty); |
|
|
51 | void ptytty_delete (PTYTTY ptytty); |
|
|
52 | int ptytty_get (PTYTTY ptytty); |
|
|
53 | void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname); |
46 | |
54 | |
47 | The default way to initialise libptytty. Must be called imemdiately as |
55 | void ptytty_close_tty (PTYTTY ptytty); |
48 | the first thing in the C<main> function, or earlier e.g. during static |
56 | int ptytty_make_controlling_tty (PTYTTY ptytty); |
49 | construction time. The earlier, the better. |
57 | void ptytty_set_utf8_mode (PTYTTY ptytty, int on); |
50 | |
58 | |
51 | This method checks wether the program runs with setuid/setgid permissions |
59 | void ptytty_init (); |
52 | and, if yes, spawns a helper process for pty/tty management. IT then |
60 | PTYTTY ptytty_create (); |
53 | drops the privileges completely, so the actual program runs without |
|
|
54 | setuid/setgid privileges. |
|
|
55 | |
61 | |
|
|
62 | void ptytty_drop_privileges (); |
56 | =item ptytty::use_helper () |
63 | void ptytty_use_helper (); |
57 | |
64 | |
58 | Tries to start a helper process that retains privileges even when the |
65 | #endif |
59 | calling process does not. This is usually called from C<ptytty::init> when |
|
|
60 | it detects that the program is running setuid or setgid, but can be called |
|
|
61 | manually if it is inconvinient to drop privileges at startup, or when |
|
|
62 | you are not running setuid/setgid but want to drop privileges (e.g. when |
|
|
63 | running as a root-started daemon). |
|
|
64 | |
66 | |
65 | This method will try not to start more than one helper process. The same |
67 | #endif |
66 | helper process can usually be used from the process starting it an all its |
|
|
67 | fork'ed (not exec'ed) children. |
|
|
68 | |
68 | |
69 | Please note that starting a helper process after dropping privileges makes |
|
|
70 | no sense. |
|
|
71 | |
|
|
72 | =item ptytty::drop_privileges () |
|
|
73 | |
|
|
74 | Drops privileges completely, i.e. sets real, effective and saved user id |
|
|
75 | to the real user id. Also aborts if this cnanot be achieved. Useful to |
|
|
76 | make sure that the process doesn't run with special privileges. |
|
|
77 | |
|
|
78 | =item bool success = ptytty::send_fd (int socket, int fd) |
|
|
79 | |
|
|
80 | Utility method to send a file descriptor over a unix domain |
|
|
81 | socket. Returns true if successful, false otherwise. This method is only |
|
|
82 | exposed for your convinience and is not required for normal operation. |
|
|
83 | |
|
|
84 | =item int fd = ptytty::recv_fd (int socket) |
|
|
85 | |
|
|
86 | Utility method to receive a file descriptor over a unix domain |
|
|
87 | socket. Returns the fd if sucecssful and C<-1> otherwise. This method |
|
|
88 | is only exposed for your convinience and is not required for normal |
|
|
89 | operation. |
|
|
90 | |
|
|
91 | =item ptytty *pty = ptytty::create () |
|
|
92 | |
|
|
93 | Creates new ptytty object. Creation does not yet do anything besides |
|
|
94 | allocating the structure. |
|
|
95 | |
|
|
96 | A static method is used because the actual ptytty implementation can |
|
|
97 | differ at runtime, so you need a dynamic object creation facility. |
|
|
98 | |
|
|
99 | =back |
|
|
100 | |
|
|
101 | |
|
|
102 | =head2 DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS |
|
|
103 | |
|
|
104 | =over 4 |
|
|
105 | |
|
|
106 | =item int pty_fd = pty->pty |
|
|
107 | |
|
|
108 | =item int tty_fd = pty->tty |
|
|
109 | |
|
|
110 | These members contain the pty and tty file descriptors, respectively. They |
|
|
111 | initially contain C<-1> until a successful to C<ptytty::get>. |
|
|
112 | |
|
|
113 | =item bool success = pty->get () |
|
|
114 | |
|
|
115 | Tries to find, allocate and initialise a new pty/tty pair. Returns C<true> |
|
|
116 | when successful. |
|
|
117 | |
|
|
118 | =item pty->login (int cmd_pid, bool login_shell, const char *hostname) |
|
|
119 | |
|
|
120 | Creates an entry in the systems session database(s) (utmp, wtmp, lastlog). |
|
|
121 | C<cmd_pid> must be the pid of the process representing the session |
|
|
122 | (such as the login shell), C<login_shell> defines wether the session is |
|
|
123 | associated with a login, which influences wether wtmp and lastlog entries |
|
|
124 | are created, and C<hostname> should identify the "hostname" the user logs |
|
|
125 | in from, which often is the value of the C<DISPLAY> variable or tty line |
|
|
126 | in case of local logins. |
|
|
127 | |
|
|
128 | Calling this method is optional. A session starts at the time of the login |
|
|
129 | call and extends until the ptytty object is destroyed. |
|
|
130 | |
|
|
131 | =item pty->close_tty () |
|
|
132 | |
|
|
133 | Closes the tty. Useful after forking in the parent/pty process. |
|
|
134 | |
|
|
135 | =item bool success = pty->make_controlling_tty () |
|
|
136 | |
|
|
137 | Tries to make the pty/tty pair the controlling terminal of the current |
|
|
138 | process. Useful after forking in the child/tty process. |
|
|
139 | |
|
|
140 | =item pty->set_utf8_mode (bool on) |
|
|
141 | |
|
|
142 | On systems supporting special UTF-8 line disciplines (e.g. Linux), tries |
|
|
143 | to enable it for the given pty. Can be called at any time to change the |
|
|
144 | mode. |
|
|
145 | |
|
|
146 | =back |
|
|
147 | |
|
|
148 | |
|
|
149 | =head1 C INTERFACE: THE ptytty FAMILY OF FUNCTIONS |
|
|
150 | |
|
|
151 | =over 4 |
|
|
152 | |
|
|
153 | =item ptytty_init () |
|
|
154 | |
|
|
155 | See C<ptytty::init ()>. |
|
|
156 | |
|
|
157 | =item PTYTTY ptytty_create () |
|
|
158 | |
|
|
159 | Creates a new opaque PTYTTY object and returns it. Do not try to access it |
|
|
160 | in any way excecp by testing it for truthness (e.g. C<if (pty) ....>). See |
|
|
161 | C<ptytty::create ()>. |
|
|
162 | |
|
|
163 | =item int ptytty_pty (PTYTTY ptytty) |
|
|
164 | |
|
|
165 | Return the pty file descriptor. See C<< pty->pty >>. |
|
|
166 | |
|
|
167 | =item int ptytty_tty (PTYTTY ptytty) |
|
|
168 | |
|
|
169 | Return the tty file descriptor. See C<< pty->tty >>. |
|
|
170 | |
|
|
171 | =item void ptytty_delete (PTYTTY ptytty) |
|
|
172 | |
|
|
173 | Destroys the PTYTTY object, freeing the pty/tty pair and cleaning up the |
|
|
174 | utmp/wtmp/lastlog databases, if initialised/used. Same as C<delete pty> in |
|
|
175 | C++. |
|
|
176 | |
|
|
177 | =item int ptytty_get (PTYTTY ptytty) |
|
|
178 | |
|
|
179 | See C<< pty->get >>, returns 0 in case of an error, non-zero otherwise. |
|
|
180 | |
|
|
181 | =item void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname) |
|
|
182 | |
|
|
183 | See C<< pty->login >>. |
|
|
184 | |
|
|
185 | =item void ptytty_close_tty (PTYTTY ptytty) |
|
|
186 | |
|
|
187 | See C<< pty->close_tty >>. |
|
|
188 | |
|
|
189 | =item int ptytty_make_controlling_tty (PTYTTY ptytty) |
|
|
190 | |
|
|
191 | See C<< pty->make_controlling_tty >>. |
|
|
192 | |
|
|
193 | =item void ptytty_set_utf8_mode (PTYTTY ptytty, int on) |
|
|
194 | |
|
|
195 | See C<< pty->set_utf8_mode >>. |
|
|
196 | |
|
|
197 | =item void ptytty_drop_privileges () |
|
|
198 | |
|
|
199 | See C<< ptytty::drop_privileges >>. |
|
|
200 | |
|
|
201 | =item void ptytty_use_helper () |
|
|
202 | |
|
|
203 | See C<< ptytty::use_helper >>. |
|
|
204 | |
|
|
205 | =back |
|
|
206 | |
|
|
207 | |
|
|
208 | =head1 BUGS |
|
|
209 | |
|
|
210 | You kiddin'? |
|
|
211 | |
|
|
212 | =head1 AUTHORS |
|
|
213 | |
|
|
214 | Emanuele Giaquinta L<< <e.giaquinta@glauco.it> >>, Marc Alexander Lehmann |
|
|
215 | L<< <rxvt-unicode@schmorp.de> >>. |
|
|