1 |
root |
1.4 |
=head1 NAME |
2 |
root |
1.1 |
|
3 |
root |
1.4 |
libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog handling |
4 |
root |
1.1 |
|
5 |
root |
1.4 |
=head1 SYNOPSIS |
6 |
root |
1.3 |
|
7 |
root |
1.4 |
-lptytty |
8 |
root |
1.3 |
|
9 |
root |
1.4 |
=head1 DESCRIPTION |
10 |
root |
1.1 |
|
11 |
root |
1.4 |
TODO |
12 |
root |
1.1 |
|
13 |
root |
1.4 |
=head1 SECURITY CONSIDERATIONS |
14 |
root |
1.1 |
|
15 |
root |
1.4 |
I<< B<It is of paramount importance that you at least read the following |
16 |
|
|
paragraph!> >> |
17 |
root |
1.1 |
|
18 |
root |
1.4 |
If you are a typical terminal-like program that just wants one or more |
19 |
|
|
ptys, you should call the C<ptytty::init ()> method (C: C<ptytty_init () |
20 |
|
|
function) as the very first thing in your program: |
21 |
root |
1.1 |
|
22 |
root |
1.4 |
int main (int argc, char *argv[]) |
23 |
|
|
{ |
24 |
|
|
// do nothing here |
25 |
|
|
ptytty::init (); |
26 |
|
|
// in C: ptytty_init (); |
27 |
root |
1.1 |
|
28 |
root |
1.4 |
// initialise, parse arguments, etc. |
29 |
|
|
} |
30 |
root |
1.1 |
|
31 |
root |
1.4 |
This checks wether the program runs setuid or setgid. If yes then it will |
32 |
|
|
fork a helper process and drop privileges. |
33 |
root |
1.1 |
|
34 |
root |
1.4 |
Some programs need finer control over if and when this helper process |
35 |
|
|
is started, and if and how to drop privileges. For those programs, the |
36 |
|
|
methods C<ptytty::use_helper> and C<ptytty::drop_privileges> are more |
37 |
|
|
useful. |
38 |
root |
1.1 |
|
39 |
root |
1.4 |
=head1 C++ INTERFACE: THE ptytty CLASS |
40 |
root |
1.3 |
|
41 |
root |
1.4 |
=head2 STATIC METHODS |
42 |
root |
1.3 |
|
43 |
root |
1.4 |
=over 4 |
44 |
root |
1.3 |
|
45 |
root |
1.4 |
=item ptytty::init () |
46 |
root |
1.3 |
|
47 |
root |
1.4 |
The default way to initialise libptytty. Must be called imemdiately as |
48 |
|
|
the first thing in the C<main> function, or earlier e.g. during static |
49 |
|
|
construction time. The earlier, the better. |
50 |
root |
1.3 |
|
51 |
root |
1.4 |
This method checks wether the program runs with setuid/setgid permissions |
52 |
|
|
and, if yes, spawns a helper process for pty/tty management. IT then |
53 |
|
|
drops the privileges completely, so the actual program runs without |
54 |
|
|
setuid/setgid privileges. |
55 |
root |
1.3 |
|
56 |
root |
1.4 |
=item ptytty::use_helper () |
57 |
root |
1.1 |
|
58 |
root |
1.4 |
Tries to start a helper process that retains privileges even when the |
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 |
|
|
|
65 |
|
|
This method will try not to start more than one helper process. The same |
66 |
|
|
helper process can usually be used from the process starting it an all its |
67 |
|
|
fork'ed (not exec'ed) children. |
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> >>. |