Repository navigation
Expand file tree
/
Copy pathrbl.3
More file actions
412 lines (371 loc) · 11.2 KB
/
Copy pathrbl.3
File metadata and controls
412 lines (371 loc) · 11.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
.TH librbl 3
.SH NAME
.B rbl_init(), rbl_close(), rbl_geterror(), rbl_setdomain(),
.B rbl_query_start(), rbl_query_check(), rbl_query_cancel(),
.B rbl_settimeout(), rbl_setcallbackint(), rbl_setcallbackctx(),
.B rbl_setdnscallback(), rbl_dns_set_query_service(),
.B rbl_dns_set_query_start(), rbl_dns_set_query_cancel(),
.B rbl_dns_set_query_waitreply(), rbl_dns_set_init(), rbl_dns_set_close(),
.B rbl_dns_set_nslist(), rbl_dns_set_config(), rbl_dns_set_trustanchor(),
.B rbl_dns_init()
\- Realtime Blacklist (RBL) service facility
.SH SYNOPSIS
#include
.I <rbl.h>
RBL *
.B rbl_init
(void *(*
.B mallocf
)(void *, size_t), void (*
.B freef
)(void *, void *p), void *
.B closure
);
unsigned char *
.B rbl_geterror
(RBL *
.B rbl
);
void
.B rbl_setdomain
(RBL *
.B rbl,
unsigned char *
.B qroot
);
RBL_STAT
.B rbl_query_start
(RBL *
.B rbl,
unsigned char *
.B query,
void **
.B qh
);
RBL_STAT
.B rbl_settimeout
(RBL *
.B rbl,
unsigned int
.B timeout
);
RBL_STAT
.B rbl_setcallbackint
(RBL *
.B rbl,
unsigned int
.B cbint
);
RBL_STAT
.B rbl_setcallbackctx
(RBL *,
.B rbl,
void *
.B ctx
);
RBL_STAT
.B rbl_setdnscallback
(RBL *,
.B rbl,
void (*
.B func
)(const void *));
void *
.B rbl_dns_set_query_service
(RBL *
.B rbl,
void *
.B svc
);
void
.B rbl_dns_set_query_cancel
(RBL *
.B rbl,
int (*
.B func
)(void *, void *));
void
.B rbl_dns_set_query_start
(RBL *
.B rbl,
int (*
.B func
)(void *, int, unsigned char *, unsigned char *, size_t, void **));
void
.B rbl_dns_set_query_waitreply
(RBL *
.B rbl,
int (*
.B func
)(void *, void *, struct timeval *, size_t *, int *, int *));
void
.B rbl_dns_set_init
(RBL *
.B rbl,
int (*
.B func
)(void **);
void
.B rbl_dns_set_close
(RBL *
.B rbl,
int (*
.B func
)(void *);
void
.B rbl_dns_set_config
(RBL *
.B rbl,
int (*
.B func
)(void *, const char *);
void
.B rbl_dns_set_nslist
(RBL *
.B rbl,
int (*
.B func
)(void *, const char *);
void
.B rbl_dns_set_trustanchor
(RBL *
.B rbl,
int (*
.B func
)(void *, const char *);
RBL_STAT
.B rbl_dns_init
(RBL *
.B rbl
);
void
.B rbl_close
(RBL *
.B rbl
);
.SH DESCRIPTION
These functions are an interface to a facility to conduct Realtime Blacklist
(RBL) queries and return their results. RBLs are described in RFC5782.
An application first initializes the package by calling
.B rbl_init().
The optional
.I mallocf
parameter is a caller-provided memory allocation function taking a pointer
to a caller-provided opaque data structure (the
.I closure
parameter) and a number of bytes to allocate. If
.I mallocf
is not provided, the default system memory allocator function
.B malloc(3)
is used. The optional
.I freef
parameter specifies a matching caller-provided memory deallocator function,
taking a pointer to a caller-provided opaque data structure (the
.I closure
parameter) and a pointer to the memory to be released. If
.I freef
is not provided, the default system memory release function
.B free(3)
is used. A handle for future use of the initialized library instance
is returned, or NULL on error and
.I errno
will be set to indicate the cause of the failure.
The
.B rbl_geterror()
function can be used to poll the library for an error string that provides
further description for the most recent failed operation.
A call to
.B rbl_setdomain()
sets the RBL's base domain. This specifies the "root" of all future queries
for the provided
.B rbl
handle to
.B qroot.
Future queries passed to this handle will be prepended to the string
provided here.
A query is initialized with a call to
.B rbl_query_start()
which takes an RBL library handle as
.B rbl,
the string to be queried as
.B query,
and a pointer to a void pointer that will be updated to contain a reference
to the initiated query as
.B qh.
A query previously started by
.I rbl_query_start()
can be canceled by calling
.B rbl_query_cancel(),
passing it an RBL library handle as
.B rbl
and a query handle as
.B qh
as previously returned when the query was started.
A query previously started by
.I rbl_query_start()
can be polled for its status or a result using
.B rbl_query_check(),
passing it an RBL library handle as
.B rbl,
a query handle as
.B qh,
a pointer to a "struct timeval" ast
.B timeout
(which can be NULL if an infinite wait is acceptable), and a pointer to
a 32-bit integer as
.B res
into which any result will be returned (or it can be NULL if the caller
doesn't actually want the result). Results are in network byte order.
If this function returns RBL_STAT_FOUND or RBL_STAT_NOTFOUND, the query
is automatically canceled and need not be passed to
.I rbl_query_cancel().
The
.B rbl_settimeout()
function can be used to change the query timeout. The default is ten seconds.
If it is useful to have the library periodically call a user-provided function
as an indication that queries are still in progress, such a function can be
registered with the
.B rbl_setdnscallback()
function. The function provided should take a void context pointer as
its sole argument.
.B rbl_setcallbackctx()
is used to tell the library what context pointer should be used, and
.B rbl_setcallbackint()
is used to tell the library what frequency, in seconds, should be used to
call that callback function. Each of these takes the corresponding RBL
library handle as its first argument, and the obvious parameter for its second.
By default, the library will use the stock system resolver to conduct DNS
queries. If alternates should be used, these can be specified using the
following functions:
.B rbl_dns_set_query_service()
sets a context pointer to the query service to be used, if any. This will
be passed as-is to the other DNS functions. It returns its previous value.
.B rbl_dns_set_query_cancel()
sets a pointer to the function that should be called to cancel an open query,
and should take the following parameters: a void pointer to the DNS query
service to be used, and a void pointer to a query handle as previously returned
by a call to
.I rbl_dns_set_query_start().
The function should return one of the DNS result codes described below.
.B rbl_dns_set_query_start()
sets a pointer to the function that should be called to initiate a new query,
and should take the following parameters: a void pointer to the DNS query
service to be used, a DNS record type (e.g. T_TXT), a pointer to a string
containing the query to be started, a pointer to a buffer into which the
reply should be written, the number of bytes available in that buffer,
and a pointer to a void pointer that will be updated to contain a unique
handle for that query once started. The function should return one of the
DNS result codes described below.
.B rbl_dns_set_query_waitreply()
sets a pointer to the function that should be called to wait for a reply
to an open query, and should take the following parameters: a void pointer
to the DNS query service to be used, a void pointer referencing the query of
interest as previously returned by a call to
.I rbl_dns_set_query_start(),
a pointer to a "struct timeval" structure indicating how long the function
should wait for a reply (or NULL if infinite waiting is acceptable),
a pointer to a "size_t" that will be updated to contain the size of the
received reply, a pointer to an integer that will contain an error code
if the query fails (can be NULL if that information is not interesting to
the caller), and a pointer to an integer that will contain a DNSSEC
status indication (can be NULL if that information is not interesting to
the caller). The function should return one of the DNS result codes
described below.
.B rbl_dns_set_init()
sets a pointer to the function that should be called when it is necessary
to initialize a resolver. The function should store a handle to the
initialized resolver and return zero, or return non-zero if initialization
could not be completed. The function specified here is called before the
first call to the query start function (see above).
.B rbl_dns_set_close()
sets a pointer to the function that should be called when it is necessary
to terminate a resolver. The function will receive a handle referencing
the resolver to be terminated, and should return zero on success or non-zero
on failure.
.B rbl_dns_set_nslist()
sets a pointer to the function that should be called when it is necessary
to change the set of nameservers that are to be used to resolve RBL queries.
The function will receive a handle referencing the active resolver and a
string containing a comma-separated list of nameservers to use. It should
return zero on success and non-zero on failure.
.B rbl_dns_set_config()
sets a pointer to the function that should be called when it is necessary
to provide a
8014
rbitrary configuration information to the resolver.
The function will receive a handle referencing the active resolver and a
string containing the configuration. It should return zero on success and
non-zero on failure.
.B rbl_dns_set_trustanchor()
sets a pointer to the function that should be called when it is necessary
to provide trust anchor information (supporting DNSSEC) to the resolver.
The function will receive a handle referencing the active resolver and a
string containing the trust anchor data. It should return zero on success and
non-zero on failure.
Calling
.B rbl_dns_init()
forces (re-)initialization of the resolver. This essentially causes
the library to call any initialization function defined by
.B rbl_dns_set_init().
When the library handle is no longer needed, it should be passed to
.B rbl_close().
.SH RETURN VALUES
The following return codes, of type RBL_STAT, can be returned:
.TP
.I RBL_STAT_OK
successful completion
.TP
.I RBL_STAT_INVALID
operation failed because an invalid parameter was provided
.TP
.I RBL_STAT_DNSERROR
operation could not be completed because of errors requesting or receiving
a DNS reply; note that this does not include a successful reply that contains
a "no record found" result, which is a successful answer
.TP
.I RBL_STAT_NORESOURCE
a caller-provided buffer was too small to complete the requested operation,
or a memory or file descriptor allocation failed
.TP
.I RBL_STAT_NOTIMPLEMENT
an optional library feature was not selected at compilation time
.TP
.I RBL_STAT_FOUND
the requested record was found in the RBL
.TP
.I RBL_STAT_NOTFOUND
the requested record was not found in the RBL (but the query did complete)
.TP
.I RBL_STAT_NOREPLY
a call to
.I rbl_query_check()
timed out before a result could be returned
.TP
.I RBL_STAT_EXPIRED
the underlying resolver reported that the query expired; this is included to
support resolvers that have an overall query timeout as well as a single
wait timeout
.SH DNS RETURN CODES
Any registered DNS functions should return one of the following result codes:
.TP
.I RBL_DNS_ERROR
An error occurred. The cause of the error can be retrieved using
.I rbl_geterror().
.TP
.I RBL_DNS_SUCCESS
The operation was successful.
.TP
.I RBL_DNS_REPLY
A reply is available (returned by the "waitreply" function).
.TP
.I RBL_DNS_NOREPLY
No reply was received by the time the query timeout was reached (returned
by the "waitreply" function).
.TP
.I RBL_DNS_EXPIRED
The query expired completely (returned by the "waitreply" function). Some
resolvers set an overall timeout for the query at start time in addition to
one for each single wait request; this code indicates the former timeout
expired.
.SH COPYRIGHT
Copyright (c) 2010-2013, The Trusted Domain Project. All rights reserved.
.SH SEE ALSO
.I intro(2)