ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/libptytty/doc/libptytty.html
Revision: 1.5
Committed: Wed Dec 12 22:16:11 2007 UTC (18 years, 9 months ago) by root
Content type: text/html
Branch: MAIN
CVS Tags: HEAD
Changes since 1.4: +0 -0 lines
State: FILE REMOVED
Log Message: 
*** empty log message ***

File Contents

# User Rev Content
1 root 1.4 <?xml version="1.0" ?>
2 root 1.1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3     <html xmlns="http://www.w3.org/1999/xhtml">
4     <head>
5     <title>libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog handling</title>
6 root 1.4 <meta http-equiv="content-type" content="text/html; charset=utf-8" />
7 root 1.1 <link rev="made" href="mailto:perl-binary@plan9.de" />
8     </head>
9    
10     <body style="background-color: white">
11    
12     <p><a name="__index__"></a></p>
13     <!-- INDEX BEGIN -->
14    
15     <ul>
16    
17     <li><a href="#name">NAME</a></li>
18     <li><a href="#synopsis">SYNOPSIS</a></li>
19     <li><a href="#description">DESCRIPTION</a></li>
20 root 1.2 <li><a href="#security_considerations">SECURITY CONSIDERATIONS</a></li>
21     <li><a href="#c___interface__the_ptytty_class">C++ INTERFACE: THE ptytty CLASS</a></li>
22     <ul>
23    
24     <li><a href="#static_methods">STATIC METHODS</a></li>
25     <li><a href="#dynamic_sessionrelated_data_members_and_methods">DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS</a></li>
26     </ul>
27    
28     <li><a href="#c_interface__the_ptytty_family_of_functions">C INTERFACE: THE ptytty FAMILY OF FUNCTIONS</a></li>
29 root 1.1 <li><a href="#bugs">BUGS</a></li>
30     <li><a href="#authors">AUTHORS</a></li>
31     </ul>
32     <!-- INDEX END -->
33    
34     <hr />
35     <p>
36     </p>
37     <h1><a name="name">NAME</a></h1>
38     <p>libptytty - OS independent and secure pty/tty and utmp/wtmp/lastlog handling</p>
39     <p>
40     </p>
41     <hr />
42     <h1><a name="synopsis">SYNOPSIS</a></h1>
43     <pre>
44 root 1.3 cc ... -lptytty</pre>
45     <pre>
46     #include &lt;libptytty.h&gt;</pre>
47     <pre>
48     // C++
49     ptytty *pty = ptytty::create ();</pre>
50     <pre>
51     if (!pty-&gt;get ())
52     // error allocating pty</pre>
53     <pre>
54     if (we want utmp)
55     pty-&gt;login (process_pid, 0, &quot;remote.host&quot;);
56     else if (we want utmp AND wtmp/lastlog)
57     pty-&gt;login (process_pid, 1, &quot;remote.host&quot;);</pre>
58     <pre>
59     // we are done with it
60     delete pty;</pre>
61     <pre>
62     // C
63     PTYTTY pty = ptytty_create ();</pre>
64     <pre>
65     if (!ptytty_get (pty))
66     // error allocating pty</pre>
67     <pre>
68     if (we want utmp)
69     ptytty_login (pty, process_pid, 0, &quot;remote.host&quot;);
70     else if (we want utmp AND wtmp/lastlog)
71     ptytty_login (pty, process_pid, 1, &quot;remote.host&quot;);</pre>
72     <pre>
73     // we are done with it
74     ptytty_delete (pty);</pre>
75 root 1.4 <p>See also the <em>eg/</em> directory, which currently contains the <em>c-sample.c</em>
76     file that spawns a loginshell from C using libptytty.</p>
77 root 1.1 <p>
78     </p>
79     <hr />
80     <h1><a name="description">DESCRIPTION</a></h1>
81 root 1.3 <p>Libptytty is a small library that offers pseudo-tty management in an
82     OS-independent way. It was created out of frustration over the many
83     differences of pty/tty handling in different operating systems for the use
84     inside <code>rxvt-unicode</code>.</p>
85     <p>In addition to offering mere pty/tty management, it also offers session
86     database support (utmp and optional wtmp/lastlog updates for login
87     shells).</p>
88     <p>It also supports fork'ing after startup and dropping privileges in the
89     calling process, so in case the calling process gets compromised by the
90     user starting the program there is less to gain, as only the helper
91     process runs with privileges (e.g. setuid/setgid), which reduces the area
92     of attack immensely.</p>
93     <p>Libptytty is written in C++, but it also offers a C-only API.</p>
94 root 1.2 <p>
95     </p>
96     <hr />
97     <h1><a name="security_considerations">SECURITY CONSIDERATIONS</a></h1>
98     <p><em><strong>It is of paramount importance that you at least read the following
99     paragraph!</strong> </em>&gt;</p>
100     <p>If you are a typical terminal-like program that just wants one or more
101     ptys, you should call the <a href="#item_init"><code>ptytty::init ()</code></a> method (C: <a href="#item_ptytty_init"><code>ptytty_init ()</code></a>
102     function) as the very first thing in your program:</p>
103     <pre>
104     int main (int argc, char *argv[])
105     {
106     // do nothing here
107     ptytty::init ();
108     // in C: ptytty_init ();</pre>
109     <pre>
110     // initialise, parse arguments, etc.
111     }</pre>
112     <p>This checks wether the program runs setuid or setgid. If yes then it will
113     fork a helper process and drop privileges.</p>
114     <p>Some programs need finer control over if and when this helper process
115     is started, and if and how to drop privileges. For those programs, the
116     methods <code>ptytty::use_helper</code> and <code>ptytty::drop_privileges</code> are more
117     useful.</p>
118 root 1.1 <p>
119     </p>
120     <hr />
121 root 1.2 <h1><a name="c___interface__the_ptytty_class">C++ INTERFACE: THE ptytty CLASS</a></h1>
122     <p>
123     </p>
124     <h2><a name="static_methods">STATIC METHODS</a></h2>
125 root 1.1 <dl>
126 root 1.4 <dt><strong><a name="item_init">ptytty::init ()</a></strong>
127    
128 root 1.2 <dd>
129 root 1.4 <p>The default way to initialise libptytty. Must be called imemdiately as
130 root 1.2 the first thing in the <code>main</code> function, or earlier e.g. during static
131 root 1.4 construction time. The earlier, the better.</p>
132 root 1.2 </dd>
133     <dd>
134     <p>This method checks wether the program runs with setuid/setgid permissions
135 root 1.4 and, if yes, spawns a helper process for pty/tty management. It then
136 root 1.2 drops the privileges completely, so the actual program runs without
137     setuid/setgid privileges.</p>
138     </dd>
139 root 1.4 </li>
140     <dt><strong><a name="item_use_helper">ptytty::use_helper ()</a></strong>
141    
142 root 1.2 <dd>
143 root 1.4 <p>Tries to start a helper process that retains privileges even when the
144 root 1.2 calling process does not. This is usually called from <code>ptytty::init</code> when
145     it detects that the program is running setuid or setgid, but can be called
146     manually if it is inconvinient to drop privileges at startup, or when
147     you are not running setuid/setgid but want to drop privileges (e.g. when
148 root 1.4 running as a root-started daemon).</p>
149 root 1.2 </dd>
150     <dd>
151     <p>This method will try not to start more than one helper process. The same
152 root 1.4 helper process can usually be used both from the process starting it and
153     all its fork'ed (not exec'ed) children.</p>
154 root 1.2 </dd>
155 root 1.4 </li>
156     <dt><strong><a name="item_drop_privileges">ptytty::drop_privileges ()</a></strong>
157    
158 root 1.2 <dd>
159 root 1.4 <p>Drops privileges completely, i.e. sets real, effective and saved user id
160     to the real user id. Also aborts if this cannot be achieved. Useful to
161     make sure that the process doesn't run with special privileges.</p>
162     </dd>
163     </li>
164     <dt><strong><a name="item_send_fd">bool success = ptytty::send_fd (int socket, int fd)</a></strong>
165    
166     <dd>
167     <p>Utility method to send a file descriptor over a unix domain
168 root 1.2 socket. Returns true if successful, false otherwise. This method is only
169 root 1.4 exposed for your convinience and is not required for normal operation.</p>
170 root 1.2 </dd>
171 root 1.4 </li>
172     <dt><strong><a name="item_recv_fd">int fd = ptytty::recv_fd (int socket)</a></strong>
173    
174 root 1.2 <dd>
175 root 1.4 <p>Utility method to receive a file descriptor over a unix domain
176 root 1.2 socket. Returns the fd if sucecssful and <code>-1</code> otherwise. This method
177     is only exposed for your convinience and is not required for normal
178 root 1.4 operation.</p>
179 root 1.2 </dd>
180 root 1.4 </li>
181     <dt><strong><a name="item_create">ptytty *pty = ptytty::create ()</a></strong>
182    
183 root 1.1 <dd>
184 root 1.4 <p>Creates new ptytty object. Creation does not yet do anything besides
185     allocating the structure.</p>
186 root 1.2 </dd>
187     <dd>
188     <p>A static method is used because the actual ptytty implementation can
189     differ at runtime, so you need a dynamic object creation facility.</p>
190     </dd>
191 root 1.4 </li>
192     </dl>
193 root 1.2 <p>
194     </p>
195     <h2><a name="dynamic_sessionrelated_data_members_and_methods">DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS</a></h2>
196     <dl>
197 root 1.4 <dt><strong><a name="item_pty">int pty_fd = pty-&gt;pty</a></strong>
198    
199     <dt><strong><a name="item_tty">int tty_fd = pty-&gt;tty</a></strong>
200    
201     <dd>
202     <p>These members contain the pty and tty file descriptors, respectively. They
203     initially contain <code>-1</code> until a successful to <code>ptytty::get</code>.</p>
204     </dd>
205     </li>
206     <dt><strong><a name="item_get">bool success = pty-&gt;get ()</a></strong>
207    
208 root 1.2 <dd>
209 root 1.4 <p>Tries to find, allocate and initialise a new pty/tty pair. Returns <code>true</code>
210     when successful.</p>
211     </dd>
212     </li>
213     <dt><strong><a name="item_login">pty-&gt;login (int cmd_pid, bool login_shell, const char *hostname)</a></strong>
214    
215     <dd>
216     <p>Creates an entry in the systems session <code>database(s)</code> (utmp, wtmp, lastlog).
217 root 1.2 <code>cmd_pid</code> must be the pid of the process representing the session
218     (such as the login shell), <code>login_shell</code> defines wether the session is
219     associated with a login, which influences wether wtmp and lastlog entries
220     are created, and <code>hostname</code> should identify the ``hostname'' the user logs
221     in from, which often is the value of the <code>DISPLAY</code> variable or tty line
222 root 1.4 in case of local logins.</p>
223 root 1.2 </dd>
224     <dd>
225     <p>Calling this method is optional. A session starts at the time of the login
226     call and extends until the ptytty object is destroyed.</p>
227     </dd>
228 root 1.4 </li>
229     <dt><strong><a name="item_close_tty">pty-&gt;close_tty ()</a></strong>
230    
231 root 1.2 <dd>
232 root 1.4 <p>Closes the tty. Useful after forking in the parent/pty process.</p>
233 root 1.2 </dd>
234 root 1.4 </li>
235     <dt><strong><a name="item_make_controlling_tty">bool success = pty-&gt;make_controlling_tty ()</a></strong>
236    
237 root 1.2 <dd>
238 root 1.4 <p>Tries to make the pty/tty pair the controlling terminal of the current
239     process. Useful after forking in the child/tty process.</p>
240 root 1.2 </dd>
241 root 1.4 </li>
242     <dt><strong><a name="item_set_utf8_mode">pty-&gt;set_utf8_mode (bool on)</a></strong>
243    
244 root 1.2 <dd>
245 root 1.4 <p>On systems supporting special UTF-8 line disciplines (e.g. Linux), this
246     tries to enable this discipline for the given pty. Can be called at any
247     time to change the mode.</p>
248 root 1.2 </dd>
249 root 1.4 </li>
250     </dl>
251 root 1.2 <p>
252     </p>
253     <hr />
254     <h1><a name="c_interface__the_ptytty_family_of_functions">C INTERFACE: THE ptytty FAMILY OF FUNCTIONS</a></h1>
255     <dl>
256 root 1.4 <dt><strong><a name="item_ptytty_init">ptytty_init ()</a></strong>
257    
258 root 1.2 <dd>
259 root 1.4 <p>See <a href="#item_init"><code>ptytty::init ()</code></a>.
260     </p>
261 root 1.2 </dd>
262     <dd>
263     <pre>
264    
265     =item PTYTTY ptytty_create ()</pre>
266     </dd>
267     <dd>
268     <p>Creates a new opaque PTYTTY object and returns it. Do not try to access it
269 root 1.4 in any way except by testing it for truthness (e.g. <code>if (pty) ....</code>). See
270 root 1.2 <a href="#item_create"><code>ptytty::create ()</code></a>.</p>
271     </dd>
272 root 1.4 </li>
273     <dt><strong><a name="item_ptytty_pty">int ptytty_pty (PTYTTY ptytty)</a></strong>
274    
275 root 1.2 <dd>
276 root 1.4 <p>Return the pty file descriptor. See <a href="#item_pty"><code>pty-&gt;pty</code></a>.
277     </p>
278 root 1.2 </dd>
279     <dd>
280     <pre>
281    
282     =item int ptytty_tty (PTYTTY ptytty)</pre>
283     </dd>
284     <dd>
285     <p>Return the tty file descriptor. See <a href="#item_tty"><code>pty-&gt;tty</code></a>.
286     </p>
287     </dd>
288     <dd>
289     <pre>
290    
291     =item void ptytty_delete (PTYTTY ptytty)</pre>
292     </dd>
293     <dd>
294     <p>Destroys the PTYTTY object, freeing the pty/tty pair and cleaning up the
295     utmp/wtmp/lastlog databases, if initialised/used. Same as <code>delete pty</code> in
296     C++.</p>
297     </dd>
298 root 1.4 </li>
299     <dt><strong><a name="item_ptytty_get">int ptytty_get (PTYTTY ptytty)</a></strong>
300    
301 root 1.2 <dd>
302 root 1.4 <p>See <a href="#item_get"><code>pty-&gt;get</code></a>, returns 0 in case of an error, non-zero otherwise.</p>
303 root 1.2 </dd>
304 root 1.4 </li>
305     <dt><strong><a name="item_ptytty_login">void ptytty_login (PTYTTY ptytty, int cmd_pid, bool login_shell, const char *hostname)</a></strong>
306    
307 root 1.2 <dd>
308 root 1.4 <p>See <a href="#item_login"><code>pty-&gt;login</code></a>.</p>
309 root 1.2 </dd>
310 root 1.4 </li>
311     <dt><strong><a name="item_ptytty_close_tty">void ptytty_close_tty (PTYTTY ptytty)</a></strong>
312    
313 root 1.2 <dd>
314 root 1.4 <p>See <a href="#item_close_tty"><code>pty-&gt;close_tty</code></a>.
315     </p>
316 root 1.2 </dd>
317     <dd>
318     <pre>
319    
320     =item int ptytty_make_controlling_tty (PTYTTY ptytty)</pre>
321     </dd>
322     <dd>
323     <p>See <a href="#item_make_controlling_tty"><code>pty-&gt;make_controlling_tty</code></a>.
324     </p>
325     </dd>
326     <dd>
327     <pre>
328    
329     =item void ptytty_set_utf8_mode (PTYTTY ptytty, int on)</pre>
330     </dd>
331     <dd>
332     <p>See <a href="#item_set_utf8_mode"><code>pty-&gt;set_utf8_mode</code></a>.</p>
333     </dd>
334 root 1.4 </li>
335     <dt><strong><a name="item_ptytty_drop_privileges">void ptytty_drop_privileges ()</a></strong>
336    
337 root 1.2 <dd>
338 root 1.4 <p>See <code>ptytty::drop_privileges</code>.
339     </p>
340 root 1.2 </dd>
341     <dd>
342     <pre>
343    
344     =item void ptytty_use_helper ()</pre>
345     </dd>
346     <dd>
347     <p>See <code>ptytty::use_helper</code>.
348    
349     </p>
350 root 1.1 </dd>
351 root 1.4 </li>
352     </dl>
353 root 1.1 <p>
354     </p>
355     <hr />
356     <h1><a name="bugs">BUGS</a></h1>
357 root 1.2 <p>You kiddin'?
358    
359     </p>
360 root 1.1 <p>
361     </p>
362     <hr />
363     <h1><a name="authors">AUTHORS</a></h1>
364     <p>Emanuele Giaquinta <em><a href="mailto:<e.giaquinta@glauco.it"><e.giaquinta@glauco.it</a></em>&gt;, Marc Alexander Lehmann
365 root 1.2 <em><a href="mailto:<rxvt-unicode@schmorp.de"><rxvt-unicode@schmorp.de</a></em>&gt;.
366     </p>
367 root 1.1
368     </body>
369    
370     </html>