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.7 by sf-exg, Wed Dec 21 00:48:52 2011 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
11 // C++
12 ptytty *pty = ptytty::create ();
13
14 if (!pty->get ())
15 // error allocating pty
16
17 if (we want utmp)
18 pty->login (process_pid, 0, "remote.host");
19 else if (we want utmp AND wtmp/lastlog)
20 pty->login (process_pid, 1, "remote.host");
21
22 // we are done with it
23 delete pty;
24
25
26 // C
27 PTYTTY pty = ptytty_create ();
28
29 if (!ptytty_get (pty))
30 // error allocating pty
31
32 if (we want utmp)
33 ptytty_login (pty, process_pid, 0, "remote.host");
34 else if (we want utmp AND wtmp/lastlog)
35 ptytty_login (pty, process_pid, 1, "remote.host");
36
37 // we are done with it
38 ptytty_delete (pty);
39
40 See also the eg/ directory, which currently contains the c-sample.c file
41 that spawns a login shell from C using libptytty.
7 42
8DESCRIPTION 43DESCRIPTION
9 TODO 44 Libptytty is a small library that offers pseudo-tty management in an
45 OS-independent way. It was created out of frustration over the many
46 differences of pty/tty handling in different operating systems for the
47 use inside "rxvt-unicode".
48
49 In addition to offering mere pty/tty management, it also offers session
50 database support (utmp and optional wtmp/lastlog updates for login
51 shells).
52
53 It also supports fork'ing after startup and dropping privileges in the
54 calling process, so in case the calling process gets compromised by the
55 user starting the program there is less to gain, as only the helper
56 process runs with privileges (e.g. setuid/setgid), which reduces the
57 area of attack immensely.
58
59 Libptytty is written in C++, but it also offers a C-only API.
10 60
11SECURITY CONSIDERATIONS 61SECURITY CONSIDERATIONS
12 *It is of paramount importance that you at least read the following 62 *It is of paramount importance that you at least read the following
13 paragraph!* 63 paragraph!*
14 64
15 If you are a typical terminal-like program that just wants one or more 65 If you write a typical terminal-like program that just wants one or more
16 ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" 66 ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()"
17 function) as the very first thing in your program: 67 function) as the very first thing in your program:
18 68
19 int main (int argc, char *argv[]) 69 int main (int argc, char *argv[])
20 { 70 {
… …
23 // in C: ptytty_init (); 73 // in C: ptytty_init ();
24 74
25 // initialise, parse arguments, etc. 75 // initialise, parse arguments, etc.
26 } 76 }
27 77
28 This checks wether the program runs setuid or setgid. If yes then it 78 This checks whether the program runs setuid or setgid. If yes then it
29 will fork a helper process and drop privileges. 79 will fork a helper process and drop privileges.
30 80
31 Some programs need finer control over if and when this helper process is 81 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 82 started, and if and how to drop privileges. For those programs, the
33 methods "ptytty::use_helper" and "ptytty::drop_privileges" are more 83 methods "ptytty::use_helper" and "ptytty::drop_privileges" (and possibly
34 useful. 84 "ptytty::sanitise_stdfd") are more useful.
35 85
36C++ INTERFACE: THE ptytty CLASS 86C++ INTERFACE: THE ptytty CLASS
37 STATIC METHODS 87 STATIC METHODS
38 ptytty::init () 88 ptytty::init ()
39 The default way to initialise libptytty. Must be called imemdiately 89 The default way to initialise libptytty. Must be called immediately
40 as the first thing in the "main" function, or earlier e.g. during 90 as the first thing in the "main" function, or earlier e.g. during
41 static construction time. The earlier, the better. 91 static construction time. The earlier, the better.
42 92
43 This method checks wether the program runs with setuid/setgid 93 This method calls "sanitise_stdfd" and then checks whether the
44 permissions and, if yes, spawns a helper process for pty/tty 94 program runs with setuid/setgid permissions and, if yes, spawns a
45 management. IT then drops the privileges completely, so the actual 95 helper process for pty/tty management. It then drops the privileges
46 program runs without setuid/setgid privileges. 96 completely, so the actual program runs without setuid/setgid
97 privileges.
47 98
48 ptytty::use_helper () 99 ptytty::use_helper ()
49 Tries to start a helper process that retains privileges even when 100 Tries to start a helper process that retains privileges even when
50 the calling process does not. This is usually called from 101 the calling process does not. This is usually called from
51 "ptytty::init" when it detects that the program is running setuid or 102 "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 103 setgid, but can be called manually if it is inconvenient to drop
53 privileges at startup, or when you are not running setuid/setgid but 104 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 105 want to drop privileges (e.g. when running as a root-started
55 daemon). 106 daemon).
56 107
57 This method will try not to start more than one helper process. The 108 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 109 same helper process can usually be used both from the process
59 an all its fork'ed (not exec'ed) children 110 starting it and all its fork'ed (not exec'ed) children.
60 111
61 ptytty::drop_privileges () 112 ptytty::drop_privileges ()
62 Drops privileges completely, i.e. sets real, effective and saved 113 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. 114 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 115 Useful to make sure that the process doesn't run with special
65 privileges. 116 privileges.
117
118 ptytty::sanitise_stdfd ()
119 Checks whether file descriptors 0, 1 and 2 (stdin, stdout and
120 stderr) are valid (open) and, if not, connects them to /dev/tty or
121 /dev/null if possible (and aborts otherwise). This is necessary
122 because libptytty might want to output error messages to those
123 descriptors, which at the time of outputting the error message,
124 might be connected to something unsuitable opened by the
125 unsuspecting program itself (this can be a security issue).
66 126
67 bool success = ptytty::send_fd (int socket, int fd) 127 bool success = ptytty::send_fd (int socket, int fd)
68 Utility method to send a file descriptor over a unix domain socket. 128 Utility method to send a file descriptor over a unix domain socket.
69 Returns true if successful, false otherwise. This method is only 129 Returns true if successful, false otherwise. This method is only
70 exposed for your convinience and is not required for normal 130 exposed for your convenience and is not required for normal
71 operation. 131 operation.
72 132
73 int fd = ptytty::recv_fd (int socket) 133 int fd = ptytty::recv_fd (int socket)
74 Utility method to receive a file descriptor over a unix domain 134 Utility method to receive a file descriptor over a unix domain
75 socket. Returns the fd if sucecssful and -1 otherwise. This method 135 socket. Returns the fd if successful and -1 otherwise. This method
76 is only exposed for your convinience and is not required for normal 136 is only exposed for your convenience and is not required for normal
77 operation. 137 operation.
78 138
79 ptytty *pty = ptytty::create () 139 ptytty *pty = ptytty::create ()
80 Creates new ptytty object. Creation does not yet do anything besides 140 Creates new ptytty object. Creation does not yet do anything besides
81 allocating the structure. 141 allocating the structure.
… …
95 "true" when successful. 155 "true" when successful.
96 156
97 pty->login (int cmd_pid, bool login_shell, const char *hostname) 157 pty->login (int cmd_pid, bool login_shell, const char *hostname)
98 Creates an entry in the systems session database(s) (utmp, wtmp, 158 Creates an entry in the systems session database(s) (utmp, wtmp,
99 lastlog). "cmd_pid" must be the pid of the process representing the 159 lastlog). "cmd_pid" must be the pid of the process representing the
100 session (such as the login shell), "login_shell" defines wether the 160 session (such as the login shell), "login_shell" defines whether the
101 session is associated with a login, which influences wether wtmp and 161 session is associated with a login, which influences whether wtmp
102 lastlog entries are created, and "hostname" should identify the 162 and lastlog entries are created, and "hostname" should identify the
103 "hostname" the user logs in from, which often is the value of the 163 "hostname" the user logs in from, which often is the value of the
104 "DISPLAY" variable or tty line in case of local logins. 164 "DISPLAY" variable or tty line in case of local logins.
105 165
106 Calling this method is optional. A session starts at the time of the 166 Calling this method is optional. A session starts at the time of the
107 login call and extends until the ptytty object is destroyed. 167 login call and extends until the ptytty object is destroyed.
… …
113 Tries to make the pty/tty pair the controlling terminal of the 173 Tries to make the pty/tty pair the controlling terminal of the
114 current process. Useful after forking in the child/tty process. 174 current process. Useful after forking in the child/tty process.
115 175
116 pty->set_utf8_mode (bool on) 176 pty->set_utf8_mode (bool on)
117 On systems supporting special UTF-8 line disciplines (e.g. Linux), 177 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 178 this tries to enable this discipline for the given pty. Can be
119 change the mode. 179 called at any time to change the mode.
120 180
121C INTERFACE: THE ptytty FAMILY OF FUNCTIONS 181C INTERFACE: THE ptytty FAMILY OF FUNCTIONS
122 ptytty_init () 182 ptytty_init ()
123 See "ptytty::init ()". 183 See "ptytty::init ()".
124 184
125 PTYTTY ptytty_create () 185 PTYTTY ptytty_create ()
126 Creates a new opaque PTYTTY object and returns it. Do not try to 186 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 187 access it in any way except by testing it for truthness (e.g. "if
128 (pty) ...."). See "ptytty::create ()". 188 (pty) ...."). See "ptytty::create ()".
129 189
130 int ptytty_pty (PTYTTY ptytty) 190 int ptytty_pty (PTYTTY ptytty)
131 Return the pty file descriptor. See "pty->pty". 191 Return the pty file descriptor. See "pty->pty".
132 192

Diff Legend

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