Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

LIBBLOCKLIST(3)            Library Functions Manual            LIBBLOCKLIST(3)

NAME
     blocklist_open, blocklist_close, blocklist_r, blocklist, blocklist_sa,
     blocklist_sa_r - Blocklistd notification library

LIBRARY
     library "libblocklist"

SYNOPSIS
     #include <blocklist.h>

     struct blocklist *
     blocklist_open(void);

     void
     blocklist_close(struct blocklist *cookie);

     int
     blocklist(int action, int fd, const char *msg);

     int
     blocklist_r(struct blocklist *cookie, int action, int fd,
         const char *msg);

     int
     blocklist_sa(int action, int fd, const struct sockaddr *sa,
         socklen_t salen, const char *msg);

     int
     blocklist_sa_r(struct blocklist *cookie, int action, int fd,
         const struct sockaddr *sa, socklen_t salen, const char *msg);

DESCRIPTION
     These functions can be used by daemons to notify blocklistd(8) about
     successful and failed remote connections so that blocklistd can block or
     release port access to prevent Denial of Service attacks.

     The function blocklist_open() creates the necessary state to communicate
     with blocklistd(8) and returns a pointer to it, or NULL on failure.

     The blocklist_close() function frees all memory and resources used.

     The blocklist() function sends a message to blocklistd(8), with an
     integer action argument specifying the type of notification, a file
     descriptor fd specifying the accepted file descriptor connected to the
     client, and an optional message in the msg argument.

     The action parameter can take these values:

     BLOCKLIST_AUTH_FAIL             There was an unsuccessful authentication
                                     attempt.

     BLOCKLIST_AUTH_OK               A user successfully authenticated.

     BLOCKLIST_ABUSIVE_BEHAVIOR      The sending daemon has detected abusive
                                     behavior from the remote system.  The
                                     remote address should be blocked as soon
                                     as possible.

     BLOCKLIST_BAD_USER              The sending daemon has determined the
                                     username presented for authentication is
                                     invalid.  The blocklistd(8) daemon
                                     compares the username to a configured
                                     list of forbidden usernames and blocks
                                     the address immediately if a forbidden
                                     username matches.  (The
                                     BLOCKLIST_BAD_USER support is not
                                     currently available.)

     The blocklist_r() function is more efficient because it keeps the
     blocklist state around.

     The blocklist_sa() and blocklist_sa_r() functions can be used with
     unconnected sockets, where getpeername(2) will not work, the server will
     pass the peer name in the message.

     In all cases the file descriptor passed in the fd argument must be
     pointing to a valid socket so that blocklistd(8) can establish ownership
     of the local endpoint using getsockname(2).

     By default, syslogd(8) is used for message logging.  The internal
     bl_create() function can be used to create the required internal state
     and specify a custom logging function.

RETURN VALUES
     The function blocklist_open() returns a cookie on success and NULL on
     failure setting errno to an appropriate value.

     The functions blocklist(), blocklist_sa(), and blocklist_sa_r() return 0
     on success and -1 on failure setting errno to an appropriate value.

SEE ALSO
     blocklistd.conf(5), blocklistd(8)

AUTHORS
     Christos Zoulas

NetBSD 10.99                    March 30, 2020                    NetBSD 10.99