1.\" $NetBSD: libblocklist.3,v 1.6 2024/08/18 16:24:40 christos Exp $ 2.\" 3.\" Copyright (c) 2015 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christos Zoulas. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd August 2, 2024 31.Dt LIBBLOCKLIST 3 32.Os 33.Sh NAME 34.Nm blocklist_open , 35.Nm blocklist_open2 , 36.Nm blocklist_close , 37.Nm blocklist_r , 38.Nm blocklist , 39.Nm blocklist_sa , 40.Nm blocklist_sa_r 41.Nd Blocklistd notification library 42.Sh LIBRARY 43.Lb libblocklist 44.Sh SYNOPSIS 45.In blocklist.h 46.Ft struct blocklist * 47.Fn blocklist_open "void" 48.Ft struct blocklist * 49.Fn blocklist_open2 "void (*logger)(int, struct syslog_data *, va_list)" 50.Ft void 51.Fn blocklist_close "struct blocklist *cookie" 52.Ft int 53.Fn blocklist "int action" "int fd" "const char *msg" 54.Ft int 55.Fn blocklist_r "struct blocklist *cookie" "int action" "int fd" "const char *msg" 56.Ft int 57.Fn blocklist_sa "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg" 58.Ft int 59.Fn blocklist_sa_r "struct blocklist *cookie" "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg" 60.Sh DESCRIPTION 61These functions can be used by daemons to notify 62.Xr blocklistd 8 63about successful and failed remote connections so that blocklistd can 64block or release port access to prevent Denial of Service attacks. 65.Pp 66The function 67.Fn blocklist_open 68creates the necessary state to communicate with 69.Xr blocklistd 8 70and returns a pointer to it, or 71.Dv NULL 72on failure. 73.Pp 74The function 75.Fn blocklist_open2 76is similar to 77.Fn blocklist_open 78but allows a 79.Fa logger 80to be specified. 81If the 82.Fa logger 83is 84.Dv NULL , 85then no logging is performed. 86.Pp 87The 88.Fn blocklist_close 89function frees all memory and resources used. 90.Pp 91The 92.Fn blocklist 93function sends a message to 94.Xr blocklistd 8 , 95with an integer 96.Ar action 97argument specifying the type of notification, 98a file descriptor 99.Ar fd 100specifying the accepted file descriptor connected to the client, 101and an optional message in the 102.Ar msg 103argument. 104.Pp 105The 106.Ar action 107parameter can take these values: 108.Bl -tag -width ".Dv BLOCKLIST_ABUSIVE_BEHAVIOR" 109.It Dv BLOCKLIST_AUTH_FAIL 110There was an unsuccessful authentication attempt. 111.It Dv BLOCKLIST_AUTH_OK 112A user successfully authenticated. 113.It Dv BLOCKLIST_ABUSIVE_BEHAVIOR 114The sending daemon has detected abusive behavior 115from the remote system. 116The remote address should 117be blocked as soon as possible. 118.It Dv BLOCKLIST_BAD_USER 119The sending daemon has determined the username 120presented for authentication is invalid. 121The 122.Xr blocklistd 8 123daemon compares the username to a configured list of forbidden 124usernames and 125blocks the address immediately if a forbidden username matches. 126(The 127.Dv BLOCKLIST_BAD_USER 128support is not currently available.) 129.El 130.Pp 131The 132.Fn blocklist_r 133function is more efficient because it keeps the blocklist state around. 134.Pp 135The 136.Fn blocklist_sa 137and 138.Fn blocklist_sa_r 139functions can be used with unconnected sockets, where 140.Xr getpeername 2 141will not work, the server will pass the peer name in the message. 142.Pp 143In all cases the file descriptor passed in the 144.Fa fd 145argument must be pointing to a valid socket so that 146.Xr blocklistd 8 147can establish ownership of the local endpoint 148using 149.Xr getsockname 2 . 150.Pp 151By default, 152.Xr syslogd 8 153is used for message logging. 154The internal 155.Fn bl_create 156function can be used to create the required internal 157state and specify a custom logging function. 158.Sh RETURN VALUES 159The function 160.Fn blocklist_open 161returns a cookie on success and 162.Dv NULL 163on failure setting 164.Dv errno 165to an appropriate value. 166.Pp 167The functions 168.Fn blocklist , 169.Fn blocklist_sa , 170and 171.Fn blocklist_sa_r 172return 173.Dv 0 174on success and 175.Dv \-1 176on failure setting 177.Dv errno 178to an appropriate value. 179.Sh SEE ALSO 180.Xr blocklistd.conf 5 , 181.Xr blocklistd 8 182.Sh AUTHORS 183.An Christos Zoulas 184