[src/trunk]: src/external/bsd/blacklist/bin Explain how configuration matchin...

[christos <christos%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/e7267a19bc97
branches:  trunk
changeset: 746382:e7267a19bc97
user:      christos <christos%NetBSD.org@localhost>
date:      Mon Mar 30 03:02:41 2020 +0000

description:
Explain how configuration matching is done.

diffstat:

 external/bsd/blacklist/bin/blacklistd.8 |  40 +++++++++++++++++++++++++++++++-
 1 files changed, 38 insertions(+), 2 deletions(-)

diffs (61 lines):

diff -r 4be89ce582f3 -r e7267a19bc97 external/bsd/blacklist/bin/blacklistd.8
--- a/external/bsd/blacklist/bin/blacklistd.8   Mon Mar 30 02:41:06 2020 +0000
+++ b/external/bsd/blacklist/bin/blacklistd.8   Mon Mar 30 03:02:41 2020 +0000
@@ -1,4 +1,4 @@
-.\" $NetBSD: blacklistd.8,v 1.20 2019/11/06 23:17:37 wiz Exp $
+.\" $NetBSD: blacklistd.8,v 1.21 2020/03/30 03:02:41 christos Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,7 +27,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd November 6, 2019
+.Dd March 29, 2020
 .Dt BLACKLISTD 8
 .Os
 .Sh NAME
@@ -65,6 +65,42 @@
 If an entry is matched, a state entry is created for that tuple.
 Each entry contains a number of tries limit and a duration.
 .Pp
+The way
+.Nm
+does configuration entry matching is by having the client side pass the
+file dscriptor associated with the connection the client wants to blacklist
+as well as passing socket credentials.
+.Pp
+The file descriptor is used to retrieve information (address and port)
+about the remote side with
+.Xr getpeername 2
+and the local side with
+.Xr getsockname 2 .
+.Pp
+By examining the port of the local side,
+.Nm
+can determine if the client program
+.Dq owns
+the port.
+By examining the optional address portion on the local side, it can match
+interfaces.
+By examining the remote address, it can match specific allow or deny rules.
+.Pp 
+Finally
+.Nm
+can examine the socket credentials to match the user in the configuration file.
+.Pp
+While this works well for TCP sockets, it cannot be relied on for unbound
+UDP sockets. 
+It is also less meaningful when it comes to connections using non-privileged
+ports.
+On the other hand, if we receive a request that has a local endpoind indicating
+UDP privileged port, we can presume that the client was privileged to be
+able to acquire that port.
+.Pp
+Once an entry is matched
+.Nm
+can perform various actions.
 If the action is
 .Dq add
 and the number of tries limit is reached, then a