1 |
root |
1.1 |
NAME |
2 |
root |
1.2 |
libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog |
3 |
root |
1.1 |
handling |
4 |
|
|
|
5 |
|
|
SYNOPSIS |
6 |
root |
1.2 |
-lptytty |
7 |
root |
1.1 |
|
8 |
|
|
DESCRIPTION |
9 |
root |
1.3 |
TODO |
10 |
|
|
|
11 |
|
|
SECURITY CONSIDERATIONS |
12 |
|
|
*It is of paramount importance that you at least read the following |
13 |
|
|
paragraph!* |
14 |
|
|
|
15 |
|
|
If you are a typical terminal-like program that just wants one or more |
16 |
|
|
ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" |
17 |
|
|
function) as the very first thing in your program: |
18 |
|
|
|
19 |
|
|
int main (int argc, char *argv[]) |
20 |
|
|
{ |
21 |
|
|
// do nothing here |
22 |
|
|
ptytty::init (); |
23 |
|
|
// in C: ptytty_init (); |
24 |
|
|
|
25 |
|
|
// initialise, parse arguments, etc. |
26 |
|
|
} |
27 |
|
|
|
28 |
|
|
This checks wether the program runs setuid or setgid. If yes then it |
29 |
|
|
will fork a helper process and drop privileges. |
30 |
|
|
|
31 |
|
|
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 |
33 |
|
|
methods "ptytty::use_helper" and "ptytty::drop_privileges" are more |
34 |
|
|
useful. |
35 |
|
|
|
36 |
|
|
C++ INTERFACE: THE ptytty CLASS |
37 |
|
|
STATIC METHODS |
38 |
|
|
ptytty::init () |
39 |
|
|
The default way to initialise libptytty. Must be called imemdiately |
40 |
|
|
as the first thing in the "main" function, or earlier e.g. during |
41 |
|
|
static construction time. The earlier, the better. |
42 |
|
|
|
43 |
|
|
This method checks wether the program runs with setuid/setgid |
44 |
|
|
permissions and, if yes, spawns a helper process for pty/tty |
45 |
|
|
management. IT then drops the privileges completely, so the actual |
46 |
|
|
program runs without setuid/setgid privileges. |
47 |
|
|
|
48 |
|
|
ptytty::use_helper () |
49 |
|
|
Tries to start a helper process that retains privileges even when |
50 |
|
|
the calling process does not. This is usually called from |
51 |
|
|
"ptytty::init" when it detects that the program is running setuid or |
52 |
|
|
setgid, but can be called manually if it is inconvinient to drop |
53 |
|
|
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 |
55 |
|
|
daemon). |
56 |
|
|
|
57 |
|
|
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 |
59 |
|
|
an all its fork'ed (not exec'ed) children |
60 |
|
|
|
61 |
|
|
ptytty::drop_privileges () |
62 |
|
|
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. |
64 |
|
|
Useful to make sure that the process doesn't run with special |
65 |
|
|
privileges. |
66 |
|
|
|
67 |
|
|
bool success = ptytty::send_fd (int socket, int fd) |
68 |
|
|
Utility method to send a file descriptor over a unix domain socket. |
69 |
|
|
Returns true if successful, false otherwise. This method is only |
70 |
|
|
exposed for your convinience and is not required for normal |
71 |
|
|
operation. |
72 |
|
|
|
73 |
|
|
int fd = ptytty::recv_fd (int socket) |
74 |
|
|
Utility method to receive a file descriptor over a unix domain |
75 |
|
|
socket. Returns the fd if sucecssful and -1 otherwise. This method |
76 |
|
|
is only exposed for your convinience and is not required for normal |
77 |
|
|
operation. |
78 |
|
|
|
79 |
|
|
ptytty *pty = ptytty::create () |
80 |
|
|
Creates new ptytty object. Creation does not yet do anything besides |
81 |
|
|
allocating the structure. |
82 |
|
|
|
83 |
|
|
A static method is used because the actual ptytty implementation can |
84 |
|
|
differ at runtime, so you need a dynamic object creation facility. |
85 |
|
|
|
86 |
|
|
DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS |
87 |
|
|
int pty_fd = pty->pty |
88 |
|
|
int tty_fd = pty->tty |
89 |
|
|
These members contain the pty and tty file descriptors, |
90 |
|
|
respectively. They initially contain -1 until a successful to |
91 |
|
|
"ptytty::get". |
92 |
|
|
|
93 |
|
|
bool success = pty->get () |
94 |
|
|
Tries to find, allocate and initialise a new pty/tty pair. Returns |
95 |
|
|
"true" when successful. |
96 |
|
|
|
97 |
|
|
pty->login (int cmd_pid, bool login_shell, const char *hostname) |
98 |
|
|
Creates an entry in the systems session database(s) (utmp, wtmp, |
99 |
|
|
lastlog). "cmd_pid" must be the pid of the process representing the |
100 |
|
|
session (such as the login shell), "login_shell" defines wether the |
101 |
|
|
session is associated with a login, which influences wether wtmp and |
102 |
|
|
lastlog entries are created, and "hostname" should identify the |
103 |
|
|
"hostname" the user logs in from, which often is the value of the |
104 |
|
|
"DISPLAY" variable or tty line in case of local logins. |
105 |
|
|
|
106 |
|
|
Calling this method is optional. A session starts at the time of the |
107 |
|
|
login call and extends until the ptytty object is destroyed. |
108 |
|
|
|
109 |
|
|
pty->close_tty () |
110 |
|
|
Closes the tty. Useful after forking in the parent/pty process. |
111 |
|
|
|
112 |
|
|
bool success = pty->make_controlling_tty () |
113 |
|
|
Tries to make the pty/tty pair the controlling terminal of the |
114 |
|
|
current process. Useful after forking in the child/tty process. |
115 |
|
|
|
116 |
|
|
pty->set_utf8_mode (bool on) |
117 |
|
|
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 |
119 |
|
|
change the mode. |
120 |
|
|
|
121 |
|
|
C INTERFACE: THE ptytty FAMILY OF FUNCTIONS |
122 |
|
|
ptytty_init () |
123 |
|
|
See "ptytty::init ()". |
124 |
|
|
|
125 |
|
|
PTYTTY ptytty_create () |
126 |
|
|
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 |
128 |
|
|
(pty) ...."). See "ptytty::create ()". |
129 |
|
|
|
130 |
|
|
int ptytty_pty (PTYTTY ptytty) |
131 |
|
|
Return the pty file descriptor. See "pty->pty". |
132 |
|
|
|
133 |
|
|
int ptytty_tty (PTYTTY ptytty) |
134 |
|
|
Return the tty file descriptor. See "pty->tty". |
135 |
|
|
|
136 |
|
|
void ptytty_delete (PTYTTY ptytty) |
137 |
|
|
Destroys the PTYTTY object, freeing the pty/tty pair and cleaning up |
138 |
|
|
the utmp/wtmp/lastlog databases, if initialised/used. Same as |
139 |
|
|
"delete pty" in C++. |
140 |
|
|
|
141 |
|
|
int ptytty_get (PTYTTY ptytty) |
142 |
|
|
See "pty->get", returns 0 in case of an error, non-zero otherwise. |
143 |
|
|
|
144 |
|
|
void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const |
145 |
|
|
char *hostname) |
146 |
|
|
See "pty->login". |
147 |
|
|
|
148 |
|
|
void ptytty_close_tty (PTYTTY ptytty) |
149 |
|
|
See "pty->close_tty". |
150 |
|
|
|
151 |
|
|
int ptytty_make_controlling_tty (PTYTTY ptytty) |
152 |
|
|
See "pty->make_controlling_tty". |
153 |
|
|
|
154 |
|
|
void ptytty_set_utf8_mode (PTYTTY ptytty, int on) |
155 |
|
|
See "pty->set_utf8_mode". |
156 |
|
|
|
157 |
|
|
void ptytty_drop_privileges () |
158 |
|
|
See "ptytty::drop_privileges". |
159 |
|
|
|
160 |
|
|
void ptytty_use_helper () |
161 |
|
|
See "ptytty::use_helper". |
162 |
root |
1.1 |
|
163 |
|
|
BUGS |
164 |
|
|
You kiddin'? |
165 |
|
|
|
166 |
|
|
AUTHORS |
167 |
|
|
Emanuele Giaquinta <e.giaquinta@glauco.it>, Marc Alexander Lehmann |
168 |
|
|
<rxvt-unicode@schmorp.de>. |
169 |
|
|
|