ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/cvsroot/libptytty/doc/libptytty.3
(Generate patch)

Comparing cvsroot/libptytty/doc/libptytty.3 (file contents):
Revision 1.3 by sf-exg, Sat Jan 21 16:17:10 2012 UTC vs.
Revision 1.4 by root, Thu Feb 25 20:21:49 2016 UTC

1.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.14) 1.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.30)
2.\" 2.\"
3.\" Standard preamble: 3.\" Standard preamble:
4.\" ======================================================================== 4.\" ========================================================================
5.de Sp \" Vertical space (when we can't use .PP) 5.de Sp \" Vertical space (when we can't use .PP)
6.if t .sp .5v 6.if t .sp .5v
… …
36.el\{\ 36.el\{\
37. ds -- \|\(em\| 37. ds -- \|\(em\|
38. ds PI \(*p 38. ds PI \(*p
39. ds L" `` 39. ds L" ``
40. ds R" '' 40. ds R" ''
41. ds C`
42. ds C'
41'br\} 43'br\}
42.\" 44.\"
43.\" Escape single quotes in literal strings from groff's Unicode transform. 45.\" Escape single quotes in literal strings from groff's Unicode transform.
44.ie \n(.g .ds Aq \(aq 46.ie \n(.g .ds Aq \(aq
45.el .ds Aq ' 47.el .ds Aq '
46.\" 48.\"
47.\" If the F register is turned on, we'll generate index entries on stderr for 49.\" If the F register is turned on, we'll generate index entries on stderr for
48.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index 50.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
49.\" entries marked with X<> in POD. Of course, you'll have to process the 51.\" entries marked with X<> in POD. Of course, you'll have to process the
50.\" output yourself in some meaningful fashion. 52.\" output yourself in some meaningful fashion.
51.ie \nF \{\ 53.\"
54.\" Avoid warning from groff about undefined register 'F'.
55.de IX
56..
57.nr rF 0
58.if \n(.g .if rF .nr rF 1
59.if (\n(rF:(\n(.g==0)) \{
60. if \nF \{
52. de IX 61. de IX
53. tm Index:\\$1\t\\n%\t"\\$2" 62. tm Index:\\$1\t\\n%\t"\\$2"
54.. 63..
55. nr % 0 64. if !\nF==2 \{
56. rr F 65. nr % 0
66. nr F 2
67. \}
68. \}
57.\} 69.\}
58.el \{\ 70.rr rF
59. de IX
60..
61.\}
62.\" 71.\"
63.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). 72.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
64.\" Fear. Run. Save yourself. No user-serviceable parts. 73.\" Fear. Run. Save yourself. No user-serviceable parts.
65. \" fudge factors for nroff and troff 74. \" fudge factors for nroff and troff
66.if n \{\ 75.if n \{\
… …
122.\} 131.\}
123.rm #[ #] #H #V #F C 132.rm #[ #] #H #V #F C
124.\" ======================================================================== 133.\" ========================================================================
125.\" 134.\"
126.IX Title "libptytty 3" 135.IX Title "libptytty 3"
127.TH libptytty 3 "2012-01-21" "1.6" "LIBPTYTTY" 136.TH libptytty 3 "2016-02-25" "1.8" "LIBPTYTTY"
128.\" For nroff, turn off justification. Always turn off hyphenation; it makes 137.\" For nroff, turn off justification. Always turn off hyphenation; it makes
129.\" way too many mistakes in technical documents. 138.\" way too many mistakes in technical documents.
130.if n .ad l 139.if n .ad l
131.nh 140.nh
132.SH "NAME" 141.SH "NAME"
… …
186calling process, so in case the calling process gets compromised by the 195calling process, so in case the calling process gets compromised by the
187user starting the program there is less to gain, as only the helper 196user starting the program there is less to gain, as only the helper
188process runs with privileges (e.g. setuid/setgid), which reduces the area 197process runs with privileges (e.g. setuid/setgid), which reduces the area
189of attack immensely. 198of attack immensely.
190.PP 199.PP
191Libptytty is written in \*(C+, but it also offers a C\-only \s-1API\s0. 200Libptytty is written in \*(C+, but it also offers a C\-only \s-1API.\s0
192.SH "SECURITY CONSIDERATIONS" 201.SH "SECURITY CONSIDERATIONS"
193.IX Header "SECURITY CONSIDERATIONS" 202.IX Header "SECURITY CONSIDERATIONS"
194\&\fI\f(BIIt is of paramount importance that you at least read the following 203\&\fI\f(BIIt is of paramount importance that you at least read the following
195paragraph!\fI\fR 204paragraph!\fI\fR
196.PP 205.PP
… …
216is started, and if and how to drop privileges. For those programs, the 225is started, and if and how to drop privileges. For those programs, the
217methods \f(CW\*(C`ptytty::use_helper\*(C'\fR and \f(CW\*(C`ptytty::drop_privileges\*(C'\fR (and possibly 226methods \f(CW\*(C`ptytty::use_helper\*(C'\fR and \f(CW\*(C`ptytty::drop_privileges\*(C'\fR (and possibly
218\&\f(CW\*(C`ptytty::sanitise_stdfd\*(C'\fR) are more useful. 227\&\f(CW\*(C`ptytty::sanitise_stdfd\*(C'\fR) are more useful.
219.SH "\*(C+ INTERFACE: THE ptytty CLASS" 228.SH "\*(C+ INTERFACE: THE ptytty CLASS"
220.IX Header " INTERFACE: THE ptytty CLASS" 229.IX Header " INTERFACE: THE ptytty CLASS"
221.SS "\s-1STATIC\s0 \s-1METHODS\s0" 230.SS "\s-1STATIC METHODS\s0"
222.IX Subsection "STATIC METHODS" 231.IX Subsection "STATIC METHODS"
223.IP "ptytty::init ()" 4 232.IP "ptytty::init ()" 4
224.IX Item "ptytty::init ()" 233.IX Item "ptytty::init ()"
225The default way to initialise libptytty. Must be called immediately as 234The default way to initialise libptytty. Must be called immediately as
226the first thing in the \f(CW\*(C`main\*(C'\fR function, or earlier e.g. during static 235the first thing in the \f(CW\*(C`main\*(C'\fR function, or earlier e.g. during static
… …
228.Sp 237.Sp
229This method calls \f(CW\*(C`sanitise_stdfd\*(C'\fR and then checks whether the program runs 238This method calls \f(CW\*(C`sanitise_stdfd\*(C'\fR and then checks whether the program runs
230with setuid/setgid permissions and, if yes, spawns a helper process for 239with setuid/setgid permissions and, if yes, spawns a helper process for
231pty/tty management. It then drops the privileges completely, so the actual 240pty/tty management. It then drops the privileges completely, so the actual
232program runs without setuid/setgid privileges. 241program runs without setuid/setgid privileges.
242.Sp
243On failure, this method terminates the process.
233.IP "ptytty::use_helper ()" 4 244.IP "ptytty::use_helper ()" 4
234.IX Item "ptytty::use_helper ()" 245.IX Item "ptytty::use_helper ()"
235Tries to start a helper process that retains privileges even when the 246Tries to start a helper process that retains privileges even when the
236calling process does not. This is usually called from \f(CW\*(C`ptytty::init\*(C'\fR when 247calling process does not. This is usually called from \f(CW\*(C`ptytty::init\*(C'\fR when
237it detects that the program is running setuid or setgid, but can be called 248it detects that the program is running setuid or setgid, but can be called
… …
240running as a root-started daemon). 251running as a root-started daemon).
241.Sp 252.Sp
242This method will try not to start more than one helper process. The same 253This method will try not to start more than one helper process. The same
243helper process can usually be used both from the process starting it and 254helper process can usually be used both from the process starting it and
244all its fork'ed (not exec'ed) children. 255all its fork'ed (not exec'ed) children.
256.Sp
257On failure, this method terminates the process.
245.IP "ptytty::drop_privileges ()" 4 258.IP "ptytty::drop_privileges ()" 4
246.IX Item "ptytty::drop_privileges ()" 259.IX Item "ptytty::drop_privileges ()"
247Drops privileges completely, i.e. sets real, effective and saved user id 260Drops privileges completely, i.e. sets real, effective and saved user
248to the real user id. Also aborts if this cannot be achieved. Useful to 261id to the real user id. Useful to make sure that the process doesn't
249make sure that the process doesn't run with special privileges. 262run with special privileges.
263.Sp
264On failure, this method terminates the process.
250.IP "ptytty::sanitise_stdfd ()" 4 265.IP "ptytty::sanitise_stdfd ()" 4
251.IX Item "ptytty::sanitise_stdfd ()" 266.IX Item "ptytty::sanitise_stdfd ()"
252Checks whether file descriptors 0, 1 and 2 (stdin, stdout and stderr) are 267Checks whether file descriptors 0, 1 and 2 (stdin, stdout and stderr)
253valid (open) and, if not, connects them to \fI/dev/tty\fR or \fI/dev/null\fR if 268are valid (open) and, if not, connects them to \fI/dev/tty\fR or
254possible (and aborts otherwise). This is necessary because libptytty might 269\&\fI/dev/null\fR if possible. This is necessary because libptytty might
255want to output error messages to those descriptors, which at the time of 270want to output error messages to those descriptors, which at the time
256outputting the error message, might be connected to something unsuitable 271of outputting the error message, might be connected to something
257opened by the unsuspecting program itself (this can be a security issue). 272unsuitable opened by the unsuspecting program itself (this can be a
273security issue).
274.Sp
275On failure, this method terminates the process.
258.IP "bool success = ptytty::send_fd (int socket, int fd)" 4 276.IP "bool success = ptytty::send_fd (int socket, int fd)" 4
259.IX Item "bool success = ptytty::send_fd (int socket, int fd)" 277.IX Item "bool success = ptytty::send_fd (int socket, int fd)"
260Utility method to send a file descriptor over a unix domain 278Utility method to send a file descriptor over a unix domain
261socket. Returns true if successful, false otherwise. This method is only 279socket. Returns true if successful, false otherwise. This method is only
262exposed for your convenience and is not required for normal operation. 280exposed for your convenience and is not required for normal operation.
… …
271Creates new ptytty object. Creation does not yet do anything besides 289Creates new ptytty object. Creation does not yet do anything besides
272allocating the structure. 290allocating the structure.
273.Sp 291.Sp
274A static method is used because the actual ptytty implementation can 292A static method is used because the actual ptytty implementation can
275differ at runtime, so you need a dynamic object creation facility. 293differ at runtime, so you need a dynamic object creation facility.
276.SS "\s-1DYNAMIC/SESSION\-RELATED\s0 \s-1DATA\s0 \s-1MEMBERS\s0 \s-1AND\s0 \s-1METHODS\s0" 294.SS "\s-1DYNAMIC/SESSION\-RELATED DATA MEMBERS AND METHODS\s0"
277.IX Subsection "DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS" 295.IX Subsection "DYNAMIC/SESSION-RELATED DATA MEMBERS AND METHODS"
278.IP "int pty_fd = pty\->pty" 4 296.IP "int pty_fd = pty\->pty" 4
279.IX Item "int pty_fd = pty->pty" 297.IX Item "int pty_fd = pty->pty"
280.PD 0 298.PD 0
281.IP "int tty_fd = pty\->tty" 4 299.IP "int tty_fd = pty\->tty" 4
282.IX Item "int tty_fd = pty->tty" 300.IX Item "int tty_fd = pty->tty"
283.PD 301.PD
284These members contain the pty and tty file descriptors, respectively. They 302These members contain the pty and tty file descriptors, respectively. They
285initially contain \f(CW\*(C`\-1\*(C'\fR until a successful to \f(CW\*(C`ptytty::get\*(C'\fR. 303initially contain \f(CW\*(C`\-1\*(C'\fR until a successful call to \f(CW\*(C`ptytty::get\*(C'\fR.
286.IP "bool success = pty\->get ()" 4 304.IP "bool success = pty\->get ()" 4
287.IX Item "bool success = pty->get ()" 305.IX Item "bool success = pty->get ()"
288Tries to find, allocate and initialise a new pty/tty pair. Returns \f(CW\*(C`true\*(C'\fR 306Tries to find, allocate and initialise a new pty/tty pair. Returns \f(CW\*(C`true\*(C'\fR
289when successful. 307when successful.
308.Sp
309If the helper process is running and there is a protocol error, this
310method terminates the process.
290.IP "pty\->login (int cmd_pid, bool login_shell, const char *hostname)" 4 311.IP "pty\->login (int cmd_pid, bool login_shell, const char *hostname)" 4
291.IX Item "pty->login (int cmd_pid, bool login_shell, const char *hostname)" 312.IX Item "pty->login (int cmd_pid, bool login_shell, const char *hostname)"
292Creates an entry in the systems session database(s) (utmp, wtmp, lastlog). 313Creates an entry in the systems session database(s) (utmp, wtmp, lastlog).
293\&\f(CW\*(C`cmd_pid\*(C'\fR must be the pid of the process representing the session 314\&\f(CW\*(C`cmd_pid\*(C'\fR must be the pid of the process representing the session
294(such as the login shell), \f(CW\*(C`login_shell\*(C'\fR defines whether the session is 315(such as the login shell), \f(CW\*(C`login_shell\*(C'\fR defines whether the session is

Diff Legend

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