1 files changed, 78 insertions, 43 deletions
diff --git a/lib/libblocklist.3 b/lib/libblocklist.3
index 77be80f89d4ff..8368624dbc6ac 100644
--- a/lib/libblocklist.3
+++ b/lib/libblocklist.3
@@ -1,4 +1,4 @@
-.\" $NetBSD: libblacklist.3,v 1.8 2017/10/22 10:31:57 abhinav Exp $
+.\" $NetBSD: libblocklist.3,v 1.10 2020/03/30 15:47:15 christos Exp $
 .\"
 .\" Copyright (c) 2015 The NetBSD Foundation, Inc.
 .\" All rights reserved.
@@ -27,62 +27,58 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 .\" POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd January 22, 2015
-.Dt LIBBLACKLIST 3
+.Dd March 30, 2020
+.Dt LIBBLOCKLIST 3
 .Os
 .Sh NAME
-.Nm blacklist_open ,
-.Nm blacklist_close ,
-.Nm blacklist_r ,
-.Nm blacklist ,
-.Nm blacklist_sa ,
-.Nm blacklist_sa_r
+.Nm blocklist_open ,
+.Nm blocklist_close ,
+.Nm blocklist_r ,
+.Nm blocklist ,
+.Nm blocklist_sa ,
+.Nm blocklist_sa_r
 .Nd Blacklistd notification library
 .Sh LIBRARY
-.Lb libblacklist
+.Lb libblocklist
 .Sh SYNOPSIS
-.In blacklist.h
-.Ft struct blacklist *
-.Fn blacklist_open "void"
+.In blocklist.h
+.Ft struct blocklist *
+.Fn blocklist_open "void"
 .Ft void
-.Fn blacklist_close "struct blacklist *cookie"
+.Fn blocklist_close "struct blocklist *cookie"
 .Ft int
-.Fn blacklist "int action" "int fd" "const char *msg"
+.Fn blocklist "int action" "int fd" "const char *msg"
 .Ft int
-.Fn blacklist_r "struct blacklist *cookie" "int action" "int fd" "const char *msg"
+.Fn blocklist_r "struct blocklist *cookie" "int action" "int fd" "const char *msg"
 .Ft int
-.Fn blacklist_sa "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg"
+.Fn blocklist_sa "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg"
 .Ft int
-.Fn blacklist_sa_r "struct blacklist *cookie" "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg"
+.Fn blocklist_sa_r "struct blocklist *cookie" "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg"
 .Sh DESCRIPTION
 These functions can be used by daemons to notify
-.Xr blacklistd 8
-about successful and failed remote connections so that blacklistd can
+.Xr blocklistd 8
+about successful and failed remote connections so that blocklistd can
 block or release port access to prevent Denial of Service attacks.
 .Pp
 The function
-.Fn blacklist_open
+.Fn blocklist_open
 creates the necessary state to communicate with
-.Xr blacklistd 8
+.Xr blocklistd 8
 and returns a pointer to it, or
 .Dv NULL
 on failure.
 .Pp
 The
-.Fn blacklist_close
+.Fn blocklist_close
 function frees all memory and resources used.
 .Pp
 The
-.Fn blacklist
+.Fn blocklist
 function sends a message to
-.Xr blacklistd 8 ,
-with an
+.Xr blocklistd 8 ,
+with an integer
 .Ar action
-argument specifying
-.Dv 1
-for a failed connection or
-.Dv 0
-for a successful connection,
+argument specifying the type of notification,
 a file descriptor
 .Ar fd
 specifying the accepted file descriptor connected to the client,
@@ -91,22 +87,61 @@ and an optional message in the
 argument.
 .Pp
 The
-.Fn blacklist_r
-function is more efficient because it keeps the blacklist state around.
+.Ar action
+parameter can take these values:
+.Bl -tag -width ".Va BLOCKLIST_ABUSIVE_BEHAVIOR"
+.It Va BLOCKLIST_AUTH_FAIL
+There was an unsuccessful authentication attempt.
+.It Va BLOCKLIST_AUTH_OK
+A user successfully authenticated.
+.It Va BLOCKLIST_ABUSIVE_BEHAVIOR
+The sending daemon has detected abusive behavior
+from the remote system.
+The remote address should
+be blocked as soon as possible.
+.It Va BLOCKLIST_BAD_USER
+The sending daemon has determined the username
+presented for authentication is invalid.
+The
+.Xr blocklistd 8
+daemon compares the username to a configured list of forbidden
+usernames and
+blocks the address immediately if a forbidden username matches.
+(The
+.Ar BLOCKLIST_BAD_USER
+support is not currently available.)
+.El
+.Pp
+The
+.Fn blocklist_r
+function is more efficient because it keeps the blocklist state around.
 .Pp
 The
-.Fn blacklist_sa
+.Fn blocklist_sa
 and
-.Fn blacklist_sa_r
+.Fn blocklist_sa_r
 functions can be used with unconnected sockets, where
 .Xr getpeername 2
 will not work, the server will pass the peer name in the message.
 .Pp
-All functions log errors to
-.Xr syslogd 8 .
+In all cases the file descriptor passed in the
+.Fa fd
+argument must be pointing to a valid socket so that
+.Xr blocklistd 8
+can establish ownership of the local endpoint
+using
+.Xr getsockname 2 .
+.Pp
+By default,
+.Xr syslogd 8
+is used for message logging.
+The internal
+.Fn bl_create
+function can be used to create the required internal
+state and specify a custom logging function.
 .Sh RETURN VALUES
 The function
-.Fn blacklist_open
+.Fn blocklist_open
 returns a cookie on success and
 .Dv NULL
 on failure setting
@@ -114,10 +149,10 @@ on failure setting
 to an appropriate value.
 .Pp
 The functions
-.Fn blacklist ,
-.Fn blacklist_sa ,
+.Fn blocklist ,
+.Fn blocklist_sa ,
 and
-.Fn blacklist_sa_r
+.Fn blocklist_sa_r
 return
 .Dv 0
 on success and
@@ -126,7 +161,7 @@ on failure setting
 .Dv errno
 to an appropriate value.
 .Sh SEE ALSO
-.Xr blacklistd.conf 5 ,
-.Xr blacklistd 8
+.Xr blocklistd.conf 5 ,
+.Xr blocklistd 8
 .Sh AUTHORS
 .An Christos Zoulas