noip.1: Describe ACL entries in terms of <address-range> and <port-range>.

[preload-hacks] / noip.1

.de VS
.sp 1
.RS
.nf
.ft B
..
.de VE
.ft R
.fi
.RE
.sp 1
..
.TH noip 1 "5 May 2005" "Straylight/Edgeware" "Preload hacks"
.SH NAME
noip \- run programs without the ability to use IP sockets
.SH SYNOPSIS
.B noip
.RI [ command
.RI [ args ...]]
.SH DESCRIPTION
The
.B noip
program runs
.I command
(by default, the user's shell, as determined by the
.B SHELL
environment variable) in an environment where attempts to use TCP/IP
networking are (mostly) transparently translated into the use of
Unix-domain sockets in a private directory.
.PP
There are many programs which use TCP/IP for their own internal
communications needs, largely unnecessarily.  This can present security
problems: even if a program binds its listening sockets to
.BR localhost ,
other users on the same system can still connect, and many such programs
don't seem to have authentication systems.
.PP
.B noip
addresses this problem by intercepting a program's networking calls and
making it use Unix-domain sockets in a private directory instead of
TCP/IP.  Now its communications are truly private to the running user.
.SS The socket directory
The
.B noip
program keeps its sockets in a directory whose name can be configured,
but by default is
.BI noip- \c
.IR username ,
where
.I username
is determined by the
.B USER
or
.B LOGNAME
environment variables, or is
.BI uid- \c
.IR realuid 
in the temporary directory, which in turn is determined by the
.B TMPDIR
or
.B TMP
environment variables, or is
.BR /tmp .
The sockets in this directory are simply named
.IB dottedquad : port
after the Internet sockets they represent.
.PP
If the socket directory does not exist when a program running under
.B noip
starts up, it is created and made readable and writable only by the
current user.  Also, it is scanned and any apparently stale sockets are
removed.
.SS Configuration
The operation of
.B noip
is controlled by a configuration file.  By default,
.B noip
reads configuration from
.B .noip
in the calling user's home directory, as determined by the
.B HOME
environment, or, failing that, looking up the effective user id in the
password database.  However, if the environment variable
.B NOIP_CONFIG
is set, then the file it names is read instead (assuming it exists; if
it doesn't, no configuration is read).
.PP
The configuration file has a simple line-based format.  A line is
ignored if it consists only of whitespace, or if its first whitespace
character is
.RB ` # '.
Otherwise, the first whitespace-delimited word is a keyword and the
remainder of the line is a value.  The following keywords are
recognized.
.TP
.BR "debug " [\fInumber\fR]
If
.I number
is nonzero, turn debugging on; if it is zero, turn debugging off.  The
default, if no
.I number
is given, is to turn debugging on.  Debugging is written to standard
error.  Some debugging is produced before the configuration file is
read; the environment variable
.B NOIP_DEBUG
can be used to control this.
.TP
.BI "socketdir " directory
Store the Unix-domain sockets in
.IR directory 
rather than the default.  The environment variable
.B NOIP_SOCKETDIR
can also be used to control which directory is used for sockets.
.TP
.BI "autoports " min "\-" max
Select which ports are used for implicit binding.  Allocating ports can
be a bit slow, since checking whether a Unix domain socket is in use is
difficult.  A wide range makes things easier, because
.B noip
starts by trying ports at random from the given range.  The environment
variable
.B NOIP_AUTOPORTS
can also be used to control which ports are assigned automatically.
.TP
.BI "realbind " acl-entry
Add an entry to the
.B realbind
access control list (ACL).  When a program attempts to
.BR bind (2)
a socket to an address, the
.B realbind
ACL is consulted.  If the address is matched, then the program is
allowed to bind a real Internet socket to that address; otherwise, the
socket is bound to a Unix-domain socket.  Three environment variables
are consulted too:
.BR NOIP_REALBIND_BEFORE ,
.BR NOIP_REALBIND ,
and
.BR NOIP_REALBIND_AFTER .
The
.B _BEFORE
rules are inserted at the front of the list; the
.B _AFTER
rules are appended on the end.  Currently, the rules in
.B NOIP_REALBIND
are also put at the end (before the
.B _AFTER
rules), though this may change later.
.TP
.BI "realconnect " acl-entry
Add an entry to the
.B realconnect
access control list (ACL).  When a program attempts to
.BR connect (2)
a socket to an address, or to contact another socket using
.BR sendto (2)
or 
.BR sendmsg (2),
the
.B realconnect
ACL is consulted.  If the destination address is matched, then the
program is allowed to contact the real Internet socket; otherwise, the
attempt is made to contact a Unix-domain socket.  Three environment variables
are consulted too:
.BR NOIP_REALCONNET_BEFORE ,
.BR NOIP_REALCONNECT ,
and
.BR NOIP_REALCONNECT_AFTER .
The
.B _BEFORE
rules are inserted at the front of the list; the
.B _AFTER
rules are appended on the end.  Currently, the rules in
.B NOIP_REALCONNECT
are also put at the end (before the
.B _AFTER
rules), though this may change later.
.PP
(Aside: An attempt to connect to a remote host may not be a hopeless failure,
even if a real IP socket is denied:
.B noip
deliberately makes no attempt to check that addresses being bound to
sockets correspond to locally available addresses; and besides, sockets
can be introduced into the directory by other programs simulating remote
servers.)
.PP
An
.I acl-entry
is a comma-separated list of entries of the form:
.IP
.BR + | \-
.I address-range
.RB [ : \c
.IR port-range ]
.PP
(The spaces in the above are optional.)
.PP
The leading sign says whether matching addresses should be
.I accepted
.RB (` + ')
or
.I denied
.RB (` \- ').
.PP
The
.I address-range
portion may be any of the following.
.TP
.B any
Matches all addresses.
.TP
.B local
Matches the address of one of the machine's network interfaces.
.TP
.I address
Matches just the given IPv4 or IPv6 address.  An
.I address
may be enclosed in square brackets; IPv6 addresses must be so enclosed,
because colons are significant in the rest of the ACL syntax.
.TP
.IB address \- address
Matches any address which falls in the given range.  Addresses are
compared lexicographically, with octets to the left given precedence
over octets to the right.
.TP
.IB address / prefix-length
Matches an address in the given network.
.PP
The
.I port-range
may be omitted (which means `match any port'), or may be a single
.I port
or a range
.IB port \- port
to match.
.PP
Range comparisons are always inclusive of both endpoints.
.PP
ACL entries are processed in the order they appear in the configuration
file.  The default action of an ACL, used if none of its entries match,
is the opposite of the last actual entry in the list: if the last entry
says `accept', then the default is to deny, and vice-versa.  If the ACL
is empty, the default is to deny all addresses.
.PP
For example, it may be useful to allow access at least to a DNS server.
This can be accomplished by adding a line
.VS
realconnect +1.2.3.4:53
.VE
to the configuration file, where 1.2.3.4 is the IP address of one of
your DNS server. 
.SS Example applications
SLIME is an Emacs extension for doing interactive programming with Lisp
systems.  It communicates with the Lisp system using TCP sockets, since
Unix-domain sockets are unavailable on Windows, and besides, they are
less well supported by Lisp implementations.  Unfortunately, when the
author wrote this program, SLIME applied no authentication on its TCP
port, allowing any local user to take over the running Lisp.  Worse,
some Lisps are unable to bind a listening socket to a particular
address, leaving the socket potentially available to anyone on the
network.  By running Emacs under
.BR noip ,
the security hole is closed completely and no messing with
authentication secrets is needed.
.PP
SSH is an excellent tool for secure communications over hostile
networks.  In particular, its ability to forward TCP connections to a
port on one side of an SSH tunnel to the other side is very useful.
However, such a forwarded port is available to all users on the source
side of the tunnel.  Using 
.B noip
and a suitable configuration, a user can restrict access to a forwarded
port to himself or a small group.
.SH BUGS
.B noip
is implemented as an
.B LD_PRELOAD
hack.  It won't work on setuid programs.  Also, perhaps more
importantly, it can't do anything to prevent a
.I malicious
program's use of networking: a program could theoretically issue sockets
system calls directly instead of using the C library calls that
.B noip
intercepts.  It is intended only as a tool for enhancing the security of
software written by well-meaning programmers who don't understand the
security aspects of writing networking code.
.PP
It's very hard to tell exactly what state a Unix-domain socket is in.
If the filesystem object isn't there, it's not active, but if it
.I is
then the socket might be in use or it might be stale.
.B noip
consults
.B /proc/net/unix
to decide whether a socket is in use, but this can fail in two ways.
Firstly, if the socket is created and renamed, the kernel doesn't
notice, and
.B noip
will think that the new name is stale.  Secondly, if the socket is
created, used, unlinked while it's still in use, and recreated, then
.B noip
will think that it's in use when in fact it's gone stale.  Don't mess
with
.BR noip 's
sockets unless you know what you're doing.
.PP
The procedure to replace a Unix-domain socket by an Internet one is
fairly thorough, but there are some missing cases.  In particular, if
the socket being bound or connected is a duplicate (using
.BR dup (2))
then only one of the copies will be fixed.  Similarly, copies owned by
child processes will be unaffected.
.PP
This manual is surprisingly long and complicated for such a simple hack.
.SH AUTHOR
Mark Wooding, <mdw@distorted.org.uk>