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.5 by root, Wed Aug 30 17:36:31 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
… …
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 wether 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.
… …
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