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