chiark - git - mdw - preload-hacks/blob - noip.1

   1 .de VS
   2 .sp 1
   3 .RS
   4 .nf
   5 .ft B
   6 ..
   7 .de VE
   8 .ft R
   9 .fi
  10 .RE
  11 .sp 1
  12 ..
  13 .TH noip 1 "5 May 2005" "Straylight/Edgeware" "Preload hacks"
  14 .SH NAME
  15 noip \- run programs without the ability to use IP sockets
  16 .SH SYNOPSIS
  17 .B noip
  18 .RI [ command
  19 .RI [ args ...]]
  20 .SH DESCRIPTION
  21 The
  22 .B noip
  23 program runs
  24 .I command
  25 (by default, the user's shell, as determined by the
  26 .B SHELL
  27 environment variable) in an environment where attempts to use TCP/IP
  28 networking are (mostly) transparently translated into the use of
  29 Unix-domain sockets in a private directory.
  30 .PP
  31 There are many programs which use TCP/IP for their own internal
  32 communications needs, largely unnecessarily.  This can present security
  33 problems: even if a program binds its listening sockets to
  34 .BR localhost ,
  35 other users on the same system can still connect, and many such programs
  36 don't seem to have authentication systems.
  37 .PP
  38 .B noip
  39 addresses this problem by intercepting a program's networking calls and
  40 making it use Unix-domain sockets in a private directory instead of
  41 TCP/IP.  Now its communications are truly private to the running user.
  42 .SS The socket directory
  43 The
  44 .B noip
  45 program keeps its sockets in a directory whose name can be configured,
  46 but by default is
  47 .BI noip- \c
  48 .IR username ,
  49 where
  50 .I username
  51 is determined by the
  52 .B USER
  53 or
  54 .B LOGNAME
  55 environment variables, or is
  56 .BI uid- \c
  57 .IR realuid
  58 in the temporary directory, which in turn is determined by the
  59 .B TMPDIR
  60 or
  61 .B TMP
  62 environment variables, or is
  63 .BR /tmp .
  64 The sockets in this directory are simply named
  65 .IB dottedquad : port
  66 after the Internet sockets they represent.
  67 .PP
  68 If the socket directory does not exist when a program running under
  69 .B noip
  70 starts up, it is created and made readable and writable only by the
  71 current user.  Also, it is scanned and any apparently stale sockets are
  72 removed.
  73 .SS Configuration
  74 The operation of
  75 .B noip
  76 is controlled by a configuration file.  By default,
  77 .B noip
  78 reads configuration from
  79 .B .noip
  80 in the calling user's home directory, as determined by the
  81 .B HOME
  82 environment, or, failing that, looking up the
  83 .I real
  84 (not effective) user id in the password database.  However, if the
  85 environment variable
  86 .B NOIP_CONFIG
  87 is set, then the file it names is read instead (assuming it exists; if
  88 it doesn't, no configuration is read).
  89 .PP
  90 The configuration file has a simple line-based format.  A line is
  91 ignored if it consists only of whitespace, or if its first whitespace
  92 character is
  93 .RB ` # '.
  94 Otherwise, the first whitespace-delimited word is a keyword and the
  95 remainder of the line is a value.  The following keywords are
  96 recognized.
  97 .TP
  98 .BR "debug " [\fInumber\fR]
  99 If
 100 .I number
 101 is nonzero, turn debugging on; if it is zero, turn debugging off.  The
 102 default, if no
 103 .I number
 104 is given, is to turn debugging on.  Debugging is written to standard
 105 error.  Some debugging is produced before the configuration file is
 106 read; the environment variable
 107 .B NOIP_DEBUG
 108 can be used to control this.
 109 .TP
 110 .BI "socketdir " directory
 111 Store the Unix-domain sockets in
 112 .IR directory
 113 rather than the default.  The environment variable
 114 .B NOIP_SOCKETDIR
 115 can also be used to control which directory is used for sockets.
 116 .TP
 117 .BI "realbind " acl-entry
 118 Add an entry to the
 119 .B realbind
 120 access control list (ACL).  When a program attempts to
 121 .BR bind (2)
 122 a socket to an address, the
 123 .B realbind
 124 ACL is consulted.  If the address is matched, then the program is
 125 allowed to bind a real Internet socket to that address; otherwise, the
 126 socket is bound to a Unix-domain socket.  Three environment variables
 127 are consulted too:
 128 .BR NOIP_REALBIND_BEFORE ,
 129 .BR NOIP_REALBIND ,
 130 and
 131 .BR NOIP_REALBIND_AFTER .
 132 The
 133 .B _BEFORE
 134 rules are inserted at the front of the list; the
 135 .B _AFTER
 136 rules are appended on the end.  Currently, the rules in
 137 .B NOIP_REALBIND
 138 are also put at the end (before the
 139 .B _AFTER
 140 rules), though this may change later.
 141 .TP
 142 .BI "realconnect " acl-entry
 143 Add an entry to the
 144 .B realconnect
 145 access control list (ACL).  When a program attempts to
 146 .BR connect (2)
 147 a socket to an address, or to contact another socket using
 148 .BR sendto (2)
 149 or
 150 .BR sendmsg (2),
 151 the
 152 .B realconnect
 153 ACL is consulted.  If the destination address is matched, then the
 154 program is allowed to contact the real Internet socket; otherwise, the
 155 attempt is made to contact a Unix-domain socket.  Three environment variables
 156 are consulted too:
 157 .BR NOIP_REALCONNET_BEFORE ,
 158 .BR NOIP_REALCONNECT ,
 159 and
 160 .BR NOIP_REALCONNECT_AFTER .
 161 The
 162 .B _BEFORE
 163 rules are inserted at the front of the list; the
 164 .B _AFTER
 165 rules are appended on the end.  Currently, the rules in
 166 .B NOIP_REALCONNECT
 167 are also put at the end (before the
 168 .B _AFTER
 169 rules), though this may change later.
 170 .PP
 171 (Aside: An attempt to connect to a remote host may not be a hopeless failure,
 172 even if a real IP socket is denied:
 173 .B noip
 174 deliberately makes no attempt to check that addresses being bound to
 175 sockets correspond to locally available addresses; and besides, sockets
 176 can be introduced into the directory by other programs simulating remote
 177 servers.)
 178 .PP
 179 An
 180 .I acl-entry
 181 is a comma-separated list of entries of the form:
 182 .IP
 183 .BR + | \-
 184 .IR address \c
 185 .RB [ \- \c
 186 .IR address | \c
 187 .BR / \c
 188 .IR mask ]| \c
 189 .BR local | any
 190 .RB [ : \c
 191 .IR port [ \c
 192 .BI \- \c
 193 .IR port ]]
 194 .PP
 195 (The spaces in the above are optional.)
 196 .PP
 197 The leading sign says whether
 198 matching addresses should be
 199 .I accepted
 200 .RB (` + ')
 201 or
 202 .I denied
 203 .RB (` \- ').
 204 .PP
 205 The IP-address portion may be any of the following
 206 .TP
 207 .B any
 208 Matches all addresses.
 209 .TP
 210 .B local
 211 Matches the address of one of the machine's network interfaces.
 212 .TP
 213 .I address
 214 Matches just the given address
 215 .TP
 216 .IB address \- address
 217 Matches any address which falls in the given range.  Addresses are
 218 compared lexicographically, with octets to the left given precedence
 219 over octets to the right.
 220 .TP
 221 .IB address / mask
 222 Matches an address in the given network.  The
 223 .I mask
 224 may be a netmask in dotted-quad form, or a one-bit-count.
 225 .PP
 226 The port portion may be omitted (which means `match any port'), or may
 227 be a single
 228 .I port
 229 or a range
 230 .IB port \- port
 231 to match.
 232 .PP
 233 Range comparisons are always inclusive of both endpoints.
 234 .PP
 235 ACL entries are processed in the order they appear in the configuration
 236 file.  The default action of an ACL, used if none of its entries match,
 237 is the opposite of the last actual entry in the list: if the last entry
 238 says `accept', then the default is to deny, and vice-versa.  If the ACL
 239 is empty, the default is to deny all addresses.
 240 .PP
 241 For example, it may be useful to allow access at least to a DNS server.
 242 This can be accomplished by adding a line
 243 .VS
 244 realconnect +1.2.3.4:52
 245 .VE
 246 to the configuration file, where 1.2.3.4 is the IP address of one of
 247 your DNS server.
 248 .SS Example applications
 249 SLIME is an Emacs extension for doing interactive programming with Lisp
 250 systems.  It communicates with the Lisp system using TCP sockets, since
 251 Unix-domain sockets are unavailable on Windows, and besides, they are
 252 less well supported by Lisp implementations.  Unfortunately, when the
 253 author wrote this program, SLIME applied no authentication on its TCP
 254 port, allowing any local user to take over the running Lisp.  Worse,
 255 some Lisps are unable to bind a listening socket to a particular
 256 address, leaving the socket potentially available to anyone on the
 257 network.  By running Emacs under
 258 .BR noip ,
 259 the security hole is closed completely and no messing with
 260 authentication secrets is needed.
 261 .PP
 262 SSH is an excellent tool for secure communications over hostile
 263 networks.  In particular, its ability to forward TCP connections to a
 264 port on one side of an SSH tunnel to the other side is very useful.
 265 However, such a forwarded port is available to all users on the source
 266 side of the tunnel.  Using
 267 .B noip
 268 and a suitable configuration, a user can restrict access to a forwarded
 269 port to himself or a small group.
 270 .SH BUGS
 271 .B noip
 272 is implemented as an
 273 .B LD_PRELOAD
 274 hack.  It won't work on setuid programs.  Also, perhaps more
 275 importantly, it can't do anything a
 276 .I malicious
 277 program use of networking: a program could theoretically issue sockets
 278 system calls directly instead of using the C library calls that
 279 .B noip
 280 intercepts.  It is intended only as a tool for enhancing the security of
 281 software written by well-meaning programmers who don't understand the
 282 security aspects of writing networking code.
 283 .PP
 284 It's very hard to tell exactly what state a Unix-domain socket is in.
 285 If the filesystem object isn't there, it's not active, but if it
 286 .I is
 287 then the socket might be in use or it might be stale.
 288 .B noip
 289 consults
 290 .B /proc/net/unix
 291 to decide whether a socket is in use, but this can fail in two ways.
 292 Firstly, if the socket is created and renamed, the kernel doesn't
 293 notice, and
 294 .B noip
 295 will think that the new name is stale.  Secondly, if the socket is
 296 created, used, unlinked while it's still in use, and recreated, then
 297 .B noip
 298 will think that it's in use when in fact it's gone stale.  Don't mess
 299 with
 300 .BR noip 's
 301 sockets unless you know what you're doing.
 302 .PP
 303 The procedure to replace a Unix-domain socket by an Internet one is
 304 fairly thorough, but there are some missing cases.  In particular, if
 305 the socket being bound or connected is a duplicate (using
 306 .BR dup (2))
 307 then only one of the copies will be fixed.  Similarly, copies owned by
 308 child processes will be unaffected.
 309 .PP
 310 This manual is surprisingly long and complicated for such a simple hack.
 311 .SH AUTHOR
 312 Mark Wooding, <mdw@nsict.org>