LIBBLOCKLIST(3)

LIBBLOCKLIST(3) | Library Functions Manual | LIBBLOCKLIST(3)

# NAME

`blocklist_open`, `blocklist_open2`, `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);

struct blocklist *
`blocklist_open2`(void (*logger)(int, struct syslog_data *, va_list));

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 function `blocklist_open2`() is similar to `blocklist_open`() but allows a logger to be specified. If the logger is `NULL`, then no logging is performed.

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

August 2, 2024 | NetBSD 10.1