ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libptytty/README
(Generate patch)

Comparing libptytty/README (file contents):
Revision 1.3 by root, Mon Jan 23 12:27:47 2006 UTC vs.
Revision 1.6 by ayin, Mon Sep 11 14:11:26 2006 UTC

1NAME 1NAME
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
5SYNOPSIS 5SYNOPSIS
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
8DESCRIPTION 41DESCRIPTION
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
11SECURITY CONSIDERATIONS 59SECURITY 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
121C INTERFACE: THE ptytty FAMILY OF FUNCTIONS 169C 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

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines