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

Comparing libptytty/README (file contents):
Revision 1.6 by ayin, Mon Sep 11 14:11:26 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
… …
34 36
35 // we are done with it 37 // we are done with it
36 ptytty_delete (pty); 38 ptytty_delete (pty);
37 39
38 See also the eg/ directory, which currently contains the c-sample.c file 40 See also the eg/ directory, which currently contains the c-sample.c file
39 that spawns a loginshell from C using libptytty. 41 that spawns a login shell from C using libptytty.
40 42
41DESCRIPTION 43DESCRIPTION
42 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
43 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
44 differences of pty/tty handling in different operating systems for the 46 differences of pty/tty handling in different operating systems for the
… …
58 60
59SECURITY CONSIDERATIONS 61SECURITY CONSIDERATIONS
60 *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
61 paragraph!* 63 paragraph!*
62 64
63 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
64 ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()" 66 ptys, you should call the "ptytty::init ()" method (C: "ptytty_init ()"
65 function) as the very first thing in your program: 67 function) as the very first thing in your program:
66 68
67 int main (int argc, char *argv[]) 69 int main (int argc, char *argv[])
68 { 70 {
… …
76 This checks whether the program runs setuid or setgid. If yes then it 78 This checks whether the program runs setuid or setgid. If yes then it
77 will fork a helper process and drop privileges. 79 will fork a helper process and drop privileges.
78 80
79 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
80 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
81 methods "ptytty::use_helper" and "ptytty::drop_privileges" are more 83 methods "ptytty::use_helper" and "ptytty::drop_privileges" (and possibly
82 useful. 84 "ptytty::sanitise_stdfd") are more useful.
83 85
84C++ INTERFACE: THE ptytty CLASS 86C++ INTERFACE: THE ptytty CLASS
85 STATIC METHODS 87 STATIC METHODS
86 ptytty::init () 88 ptytty::init ()
87 The default way to initialise libptytty. Must be called imemdiately 89 The default way to initialise libptytty. Must be called immediately
88 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
89 static construction time. The earlier, the better. 91 static construction time. The earlier, the better.
90 92
91 This method checks whether the program runs with setuid/setgid 93 This method calls "sanitise_stdfd" and then checks whether the
92 permissions and, if yes, spawns a helper process for pty/tty 94 program runs with setuid/setgid permissions and, if yes, spawns a
93 management. It then drops the privileges completely, so the actual 95 helper process for pty/tty management. It then drops the privileges
94 program runs without setuid/setgid privileges. 96 completely, so the actual program runs without setuid/setgid
97 privileges.
95 98
96 ptytty::use_helper () 99 ptytty::use_helper ()
97 Tries to start a helper process that retains privileges even when 100 Tries to start a helper process that retains privileges even when
98 the calling process does not. This is usually called from 101 the calling process does not. This is usually called from
99 "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
100 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
101 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
102 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
103 daemon). 106 daemon).
104 107
105 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
… …
110 Drops privileges completely, i.e. sets real, effective and saved 113 Drops privileges completely, i.e. sets real, effective and saved
111 user id to the real user id. Also aborts if this cannot be achieved. 114 user id to the real user id. Also aborts if this cannot be achieved.
112 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
113 privileges. 116 privileges.
114 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).
126
115 bool success = ptytty::send_fd (int socket, int fd) 127 bool success = ptytty::send_fd (int socket, int fd)
116 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.
117 Returns true if successful, false otherwise. This method is only 129 Returns true if successful, false otherwise. This method is only
118 exposed for your convinience and is not required for normal 130 exposed for your convenience and is not required for normal
119 operation. 131 operation.
120 132
121 int fd = ptytty::recv_fd (int socket) 133 int fd = ptytty::recv_fd (int socket)
122 Utility method to receive a file descriptor over a unix domain 134 Utility method to receive a file descriptor over a unix domain
123 socket. Returns the fd if sucecssful and -1 otherwise. This method 135 socket. Returns the fd if successful and -1 otherwise. This method
124 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
125 operation. 137 operation.
126 138
127 ptytty *pty = ptytty::create () 139 ptytty *pty = ptytty::create ()
128 Creates new ptytty object. Creation does not yet do anything besides 140 Creates new ptytty object. Creation does not yet do anything besides
129 allocating the structure. 141 allocating the structure.
… …
144 156
145 pty->login (int cmd_pid, bool login_shell, const char *hostname) 157 pty->login (int cmd_pid, bool login_shell, const char *hostname)
146 Creates an entry in the systems session database(s) (utmp, wtmp, 158 Creates an entry in the systems session database(s) (utmp, wtmp,
147 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
148 session (such as the login shell), "login_shell" defines whether the 160 session (such as the login shell), "login_shell" defines whether the
149 session is associated with a login, which influences whether wtmp and 161 session is associated with a login, which influences whether wtmp
150 lastlog entries are created, and "hostname" should identify the 162 and lastlog entries are created, and "hostname" should identify the
151 "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
152 "DISPLAY" variable or tty line in case of local logins. 164 "DISPLAY" variable or tty line in case of local logins.
153 165
154 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
155 login call and extends until the ptytty object is destroyed. 167 login call and extends until the ptytty object is destroyed.

Diff Legend

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