1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 3. All advertising materials mentioning features or use of this software 13.\" must display the following acknowledgement: 14.\" This product includes software developed by the University of 15.\" California, Berkeley and its contributors. 16.\" 4. Neither the name of the University nor the names of its contributors 17.\" may be used to endorse or promote products derived from this software 18.\" without specific prior written permission. 19.\" 20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 23.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 30.\" SUCH DAMAGE. 31.\" 32.\" From: @(#)rcmd.3 8.1 (Berkeley) 6/4/93 33.\" $FreeBSD$ 34.\" 35.Dd February 15, 1996 36.Dt RCMD 3 37.Os BSD 4.2 38.Sh NAME 39.Nm rcmd , 40.Nm rresvport , 41.Nm iruserok , 42.Nm ruserok , 43.Nm rresvport_af , 44.Nm iruserok_af , 45.Nm ruserok_af 46.Nd routines for returning a stream to a remote command 47.Sh SYNOPSIS 48.Fd #include <unistd.h> 49.Ft int 50.Fn rcmd "char **ahost" "int inport" "const char *locuser" "const char *remuser" "const char *cmd" "int *fd2p" 51.Ft int 52.Fn rresvport "int *port" 53.Ft int 54.Fn iruserok "u_long raddr" "int superuser" "const char *ruser" "const char *luser" 55.Ft int 56.Fn ruserok "const char *rhost" "int superuser" "const char *ruser" "const char *luser" 57.Ft int 58.Fn rresvport_af "int *port" "int family" 59.Ft int 60.Fn iruserok_af "void *raddr" "int superuser" "const char *ruser" "const char *luser" "int af" 61.Ft int 62.Fn ruserok_af "const char *rhost" "int superuser" "const char *ruser" "const char *luser" "int af" 63.Sh DESCRIPTION 64The 65.Fn rcmd 66function 67is used by the super-user to execute a command on 68a remote machine using an authentication scheme based 69on reserved port numbers. 70The 71.Fn rresvport 72function 73returns a descriptor to a socket 74with an address in the privileged port space. 75The 76.Fn ruserok 77function 78is used by servers 79to authenticate clients requesting service with 80.Fn rcmd . 81All three functions are present in the same file and are used 82by the 83.Xr rshd 8 84server (among others). 85.Pp 86The 87.Fn rcmd 88function 89looks up the host 90.Fa *ahost 91using 92.Xr gethostbyname 3 , 93returning \-1 if the host does not exist. 94Otherwise 95.Fa *ahost 96is set to the standard name of the host 97and a connection is established to a server 98residing at the well-known Internet port 99.Fa inport . 100.Pp 101If the connection succeeds, 102a socket in the Internet domain of type 103.Dv SOCK_STREAM 104is returned to the caller, and given to the remote 105command as 106.Em stdin 107and 108.Em stdout . 109If 110.Fa fd2p 111is non-zero, then an auxiliary channel to a control 112process will be set up, and a descriptor for it will be placed 113in 114.Fa *fd2p . 115The control process will return diagnostic 116output from the command (unit 2) on this channel, and will also 117accept bytes on this channel as being 118.Tn UNIX 119signal numbers, to be 120forwarded to the process group of the command. 121If 122.Fa fd2p 123is 0, then the 124.Em stderr 125(unit 2 of the remote 126command) will be made the same as the 127.Em stdout 128and no 129provision is made for sending arbitrary signals to the remote process, 130although you may be able to get its attention by using out-of-band data. 131.Pp 132The protocol is described in detail in 133.Xr rshd 8 . 134.Pp 135The 136.Fn rresvport 137function is used to obtain a socket with a privileged 138address bound to it. This socket is suitable for use 139by 140.Fn rcmd 141and several other functions. Privileged Internet ports are those 142in the range 0 to 1023. Only the super-user 143is allowed to bind an address of this sort to a socket. 144.Pp 145The 146.Fn iruserok 147and 148.Fn ruserok 149functions take a remote host's IP address or name, as returned by the 150.Xr gethostbyname 3 151routines, two user names and a flag indicating whether the local user's 152name is that of the super-user. 153Then, if the user is 154.Em NOT 155the super-user, it checks the 156.Pa /etc/hosts.equiv 157file. 158If that lookup is not done, or is unsuccessful, the 159.Pa .rhosts 160in the local user's home directory is checked to see if the request for 161service is allowed. 162.Pp 163If this file does not exist, is not a regular file, is owned by anyone 164other than the user or the super-user, or is writable by anyone other 165than the owner, the check automatically fails. 166Zero is returned if the machine name is listed in the 167.Dq Pa hosts.equiv 168file, or the host and remote user name are found in the 169.Dq Pa .rhosts 170file; otherwise 171.Fn iruserok 172and 173.Fn ruserok 174return \-1. 175If the local domain (as obtained from 176.Xr gethostname 3 ) 177is the same as the remote domain, only the machine name need be specified. 178.Pp 179The 180.Fn iruserok 181function is strongly preferred for security reasons. 182It requires trusting the local DNS at most, while the 183.Fn ruserok 184function requires trusting the entire DNS, which can be spoofed. 185.Pp 186Functions with ``_af'' suffix, i.e. 187.Fn rresvport_af , 188.Fn iruserok_af and 189.Fn ruserok_af , 190works just as same as functions without ``_af'', and is capable of 191handling both IPv6 port and IPv4 port. 192To switch address family, 193.Fa af 194argument must be filled with 195.Dv AF_INET 196or 197.Dv AF_INET6 . 198.Sh DIAGNOSTICS 199The 200.Fn rcmd 201function 202returns a valid socket descriptor on success. 203It returns \-1 on error and prints a diagnostic message on the standard error. 204.Pp 205The 206.Fn rresvport 207function 208returns a valid, bound socket descriptor on success. 209It returns \-1 on error with the global value 210.Va errno 211set according to the reason for failure. 212The error code 213.Dv EAGAIN 214is overloaded to mean ``All network ports in use.'' 215.Sh SEE ALSO 216.Xr rlogin 1 , 217.Xr rsh 1 , 218.Xr intro 2 , 219.Xr rexec 3 , 220.Xr rexecd 8 , 221.Xr rlogind 8 , 222.Xr rshd 8 223.Pp 224W. Stevens and M. Thomas, ``Advanced Socket API for IPv6,'' 225RFC2292. 226.Sh HISTORY 227These 228functions appeared in 229.Bx 4.2 . 230.Fn rresvport_af 231appeared in RFC2292, and implemented by WIDE project 232for Hydrangea IPv6 protocol stack kit. 233.Fn iruserok_af 234and 235.Fn rusreok_af 236are proposed and implemented by WIDE project 237for Hydrangea IPv6 protocol stack kit. 238