1.\" $NetBSD: libblacklist.3,v 1.3 2015/01/25 23:09:28 wiz 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 January 22, 2015 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 a 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 80.Ar action 81argument specifying 82.Dv 1 83for a failed connection or 84.Dv 0 85for a successful connection, 86a file descriptor 87.Ar fd 88specifying the accepted file descriptor connected to the client, 89and an optional message in the 90.Ar msg 91argument. 92.Pp 93The 94.Fn blacklist_r 95function is more efficient because it keeps the blacklist state around. 96.Pp 97The 98.Fn blacklist_sa 99and 100.Fn blacklist_sa_r 101functions can be used with unconnected sockets, where 102.Xr getpeername 2 103will not work, the server will pass the peer name in the message. 104.Pp 105All functions log errors to 106.Xr syslogd 8 . 107.Sh RETURN VALUES 108The function 109.Fn bl_open 110returns a cookie on success and 111.Dv NULL 112on failure setting errno to an appropriate value. 113.Pp 114The 115.Fn bl_send 116function returns 117.Dv 0 118on success and 119.Dv -1 120on failure setting errno to an appropriate value. 121.Sh SEE ALSO 122.Xr blacklistd.conf 5 , 123.Xr blacklistd 8 124.Sh AUTHORS 125.An Christos Zoulas 126