1.\" $NetBSD: libblacklist.3,v 1.10 2020/03/30 15:47:15 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 March 30, 2020 31.Dt LIBBLACKLIST 3 32.Os 33.Sh NAME 34.Nm blacklist_open , 35.Nm blacklist_close , 36.Nm blacklist_r , 37.Nm blacklist , 38.Nm blacklist_sa , 39.Nm blacklist_sa_r 40.Nd Blacklistd notification library 41.Sh LIBRARY 42.Lb libblacklist 43.Sh SYNOPSIS 44.In blacklist.h 45.Ft struct blacklist * 46.Fn blacklist_open "void" 47.Ft void 48.Fn blacklist_close "struct blacklist *cookie" 49.Ft int 50.Fn blacklist "int action" "int fd" "const char *msg" 51.Ft int 52.Fn blacklist_r "struct blacklist *cookie" "int action" "int fd" "const char *msg" 53.Ft int 54.Fn blacklist_sa "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg" 55.Ft int 56.Fn blacklist_sa_r "struct blacklist *cookie" "int action" "int fd" "const struct sockaddr *sa" "socklen_t salen" "const char *msg" 57.Sh DESCRIPTION 58These functions can be used by daemons to notify 59.Xr blacklistd 8 60about successful and failed remote connections so that blacklistd can 61block or release port access to prevent Denial of Service attacks. 62.Pp 63The function 64.Fn blacklist_open 65creates the necessary state to communicate with 66.Xr blacklistd 8 67and returns a pointer to it, or 68.Dv NULL 69on failure. 70.Pp 71The 72.Fn blacklist_close 73function frees all memory and resources used. 74.Pp 75The 76.Fn blacklist 77function sends a message to 78.Xr blacklistd 8 , 79with an integer 80.Ar action 81argument specifying the type of notification, 82a file descriptor 83.Ar fd 84specifying the accepted file descriptor connected to the client, 85and an optional message in the 86.Ar msg 87argument. 88.Pp 89The 90.Ar action 91parameter can take these values: 92.Bl -tag -width ".Va BLACKLIST_ABUSIVE_BEHAVIOR" 93.It Va BLACKLIST_AUTH_FAIL 94There was an unsuccessful authentication attempt. 95.It Va BLACKLIST_AUTH_OK 96A user successfully authenticated. 97.It Va BLACKLIST_ABUSIVE_BEHAVIOR 98The sending daemon has detected abusive behavior 99from the remote system. 100The remote address should 101be blocked as soon as possible. 102.It Va BLACKLIST_BAD_USER 103The sending daemon has determined the username 104presented for authentication is invalid. 105The 106.Xr blacklistd 8 107daemon compares the username to a configured list of forbidden 108usernames and 109blocks the address immediately if a forbidden username matches. 110(The 111.Ar BLACKLIST_BAD_USER 112support is not currently available.) 113.El 114.Pp 115The 116.Fn blacklist_r 117function is more efficient because it keeps the blacklist state around. 118.Pp 119The 120.Fn blacklist_sa 121and 122.Fn blacklist_sa_r 123functions can be used with unconnected sockets, where 124.Xr getpeername 2 125will not work, the server will pass the peer name in the message. 126.Pp 127In all cases the file descriptor passed in the 128.Fa fd 129argument must be pointing to a valid socket so that 130.Xr blacklistd 8 131can establish ownership of the local endpoint 132using 133.Xr getsockname 2 . 134.Pp 135By default, 136.Xr syslogd 8 137is used for message logging. 138The internal 139.Fn bl_create 140function can be used to create the required internal 141state and specify a custom logging function. 142.Sh RETURN VALUES 143The function 144.Fn blacklist_open 145returns a cookie on success and 146.Dv NULL 147on failure setting 148.Dv errno 149to an appropriate value. 150.Pp 151The functions 152.Fn blacklist , 153.Fn blacklist_sa , 154and 155.Fn blacklist_sa_r 156return 157.Dv 0 158on success and 159.Dv \-1 160on failure setting 161.Dv errno 162to an appropriate value. 163.Sh SEE ALSO 164.Xr blacklistd.conf 5 , 165.Xr blacklistd 8 166.Sh AUTHORS 167.An Christos Zoulas 168