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

Comparing libptytty/README (file contents):
Revision 1.4 by root, Mon Jan 23 12:37:09 2006 UTC vs.
Revision 1.7 by sf-exg, Wed Dec 21 00:48:52 2011 UTC

… …
4 4
5SYNOPSIS 5SYNOPSIS
6 cc ... -lptytty 6 cc ... -lptytty
7 7
8 #include <libptytty.h> 8 #include <libptytty.h>
9
9 10
10 // C++ 11 // C++
11 ptytty *pty = ptytty::create (); 12 ptytty *pty = ptytty::create ();
12 13
13 if (!pty->get ()) 14 if (!pty->get ())
… …
19 pty->login (process_pid, 1, "remote.host"); 20 pty->login (process_pid, 1, "remote.host");
20 21
21 // we are done with it 22 // we are done with it
22 delete pty; 23 delete pty;
23 24
25
24 // C 26 // C
25 PTYTTY pty = ptytty_create (); 27 PTYTTY pty = ptytty_create ();
26 28
27 if (!ptytty_get (pty)) 29 if (!ptytty_get (pty))
28 // error allocating pty 30 // error allocating pty
… …
32 else if (we want utmp AND wtmp/lastlog) 34 else if (we want utmp AND wtmp/lastlog)
33 ptytty_login (pty, process_pid, 1, "remote.host"); 35 ptytty_login (pty, process_pid, 1, "remote.host");
34 36
35 // we are done with it 37 // we are done with it
36 ptytty_delete (pty); 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.
37 42
38DESCRIPTION 43DESCRIPTION
39 Libptytty is a small library that offers pseudo-tty management in an 44 Libptytty is a small library that offers pseudo-tty management in an
40 OS-independent way. It was created out of frustration over the many 45 OS-independent way. It was created out of frustration over the many
41 differences of pty/tty handling in different operating systems for the 46 differences of pty/tty handling in different operating systems for the
… …
55 60
56SECURITY CONSIDERATIONS 61SECURITY CONSIDERATIONS
57 *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
58 paragraph!* 63 paragraph!*
59 64
60 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
61 ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" 66 ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()"
62 function) as the very first thing in your program: 67 function) as the very first thing in your program:
63 68
64 int main (int argc, char *argv[]) 69 int main (int argc, char *argv[])
65 { 70 {
… …
68 // in C: ptytty_init (); 73 // in C: ptytty_init ();
69 74
70 // initialise, parse arguments, etc. 75 // initialise, parse arguments, etc.
71 } 76 }
72 77
73 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
74 will fork a helper process and drop privileges. 79 will fork a helper process and drop privileges.
75 80
76 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
77 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
78 methods "ptytty::use_helper" and "ptytty::drop_privileges" are more 83 methods "ptytty::use_helper" and "ptytty::drop_privileges" (and possibly
79 useful. 84 "ptytty::sanitise_stdfd") are more useful.
80 85
81C++ INTERFACE: THE ptytty CLASS 86C++ INTERFACE: THE ptytty CLASS
82 STATIC METHODS 87 STATIC METHODS
83 ptytty::init () 88 ptytty::init ()
84 The default way to initialise libptytty. Must be called imemdiately 89 The default way to initialise libptytty. Must be called immediately
85 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
86 static construction time. The earlier, the better. 91 static construction time. The earlier, the better.
87 92
88 This method checks wether the program runs with setuid/setgid 93 This method calls "sanitise_stdfd" and then checks whether the
89 permissions and, if yes, spawns a helper process for pty/tty 94 program runs with setuid/setgid permissions and, if yes, spawns a
90 management. IT then drops the privileges completely, so the actual 95 helper process for pty/tty management. It then drops the privileges
91 program runs without setuid/setgid privileges. 96 completely, so the actual program runs without setuid/setgid
97 privileges.
92 98
93 ptytty::use_helper () 99 ptytty::use_helper ()
94 Tries to start a helper process that retains privileges even when 100 Tries to start a helper process that retains privileges even when
95 the calling process does not. This is usually called from 101 the calling process does not. This is usually called from
96 "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
97 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
98 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
99 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
100 daemon). 106 daemon).
101 107
102 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
103 same helper process cna usually be used form the process starting it 109 same helper process can usually be used both from the process
104 an all its fork'ed (not exec'ed) children 110 starting it and all its fork'ed (not exec'ed) children.
105 111
106 ptytty::drop_privileges () 112 ptytty::drop_privileges ()
107 Drops privileges completely, i.e. sets real, effective and saved 113 Drops privileges completely, i.e. sets real, effective and saved
108 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.
109 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
110 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).
111 126
112 bool success = ptytty::send_fd (int socket, int fd) 127 bool success = ptytty::send_fd (int socket, int fd)
113 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.
114 Returns true if successful, false otherwise. This method is only 129 Returns true if successful, false otherwise. This method is only
115 exposed for your convinience and is not required for normal 130 exposed for your convenience and is not required for normal
116 operation. 131 operation.
117 132
118 int fd = ptytty::recv_fd (int socket) 133 int fd = ptytty::recv_fd (int socket)
119 Utility method to receive a file descriptor over a unix domain 134 Utility method to receive a file descriptor over a unix domain
120 socket. Returns the fd if sucecssful and -1 otherwise. This method 135 socket. Returns the fd if successful and -1 otherwise. This method
121 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
122 operation. 137 operation.
123 138
124 ptytty *pty = ptytty::create () 139 ptytty *pty = ptytty::create ()
125 Creates new ptytty object. Creation does not yet do anything besides 140 Creates new ptytty object. Creation does not yet do anything besides
126 allocating the structure. 141 allocating the structure.
… …
140 "true" when successful. 155 "true" when successful.
141 156
142 pty->login (int cmd_pid, bool login_shell, const char *hostname) 157 pty->login (int cmd_pid, bool login_shell, const char *hostname)
143 Creates an entry in the systems session database(s) (utmp, wtmp, 158 Creates an entry in the systems session database(s) (utmp, wtmp,
144 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
145 session (such as the login shell), "login_shell" defines wether the 160 session (such as the login shell), "login_shell" defines whether the
146 session is associated with a login, which influences wether wtmp and 161 session is associated with a login, which influences whether wtmp
147 lastlog entries are created, and "hostname" should identify the 162 and lastlog entries are created, and "hostname" should identify the
148 "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
149 "DISPLAY" variable or tty line in case of local logins. 164 "DISPLAY" variable or tty line in case of local logins.
150 165
151 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
152 login call and extends until the ptytty object is destroyed. 167 login call and extends until the ptytty object is destroyed.
… …
158 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
159 current process. Useful after forking in the child/tty process. 174 current process. Useful after forking in the child/tty process.
160 175
161 pty->set_utf8_mode (bool on) 176 pty->set_utf8_mode (bool on)
162 On systems supporting special UTF-8 line disciplines (e.g. Linux), 177 On systems supporting special UTF-8 line disciplines (e.g. Linux),
163 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
164 change the mode. 179 called at any time to change the mode.
165 180
166C INTERFACE: THE ptytty FAMILY OF FUNCTIONS 181C INTERFACE: THE ptytty FAMILY OF FUNCTIONS
167 ptytty_init () 182 ptytty_init ()
168 See "ptytty::init ()". 183 See "ptytty::init ()".
169 184
170 PTYTTY ptytty_create () 185 PTYTTY ptytty_create ()
171 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
172 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
173 (pty) ...."). See "ptytty::create ()". 188 (pty) ...."). See "ptytty::create ()".
174 189
175 int ptytty_pty (PTYTTY ptytty) 190 int ptytty_pty (PTYTTY ptytty)
176 Return the pty file descriptor. See "pty->pty". 191 Return the pty file descriptor. See "pty->pty".
177 192

Diff Legend

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