libgslutil
1.2.3
|
Enumerations | |
enum | ipfilter_policy_t { ipfilter_policy_accept, ipfilter_policy_reject } |
Default policy for IP filter. More... | |
Functions | |
struct ipfilter_t * | ipfilter_new (void)) |
Instantiate a new IP filter object. More... | |
void | ipfilter_free (struct ipfilter_t *ipf) |
Free an IP filter object. More... | |
enum ipfilter_policy_t | ipfilter (const struct ipfilter_t *ipf, const struct sockaddr *sa) |
Filter address. More... | |
enum ipfilter_policy_t | ipfilter_policy_get (const struct ipfilter_t *ipf)) |
Retrieve an IP filter's default accept/reject policy. More... | |
void | ipfilter_policy_set (struct ipfilter_t *ipf, enum ipfilter_policy_t policy)) |
Set an IP filter's default accept/reject policy. More... | |
int | ipfilter_add (struct ipfilter_t *ipf, const struct sockaddr *sa, int bits, enum ipfilter_policy_t policy) |
Add an entry to an IP filter. More... | |
int | ipfilter_add_str (struct ipfilter_t *ipf, const char *str, const char **endp) |
Add entry based on string. More... | |
int | ipfilter_add_commastr (struct ipfilter_t *ipf, const char *str, const char **errp) |
Add entries based on comma-separated string. More... | |
void | ipfilter_debug_dump (const struct ipfilter_t *ipf, char *buf, int sz)) |
Dump IP filter to string for debugging. More... | |
This set of routines provides a way to match an IP address against a list of accepted/rejected addresses. Its purpose is similar to that of TCP Wrappers, although the implementation is more limited. However, it is much more convenient for integration allowing fine-grained checks.
The filter's structure is a simple list of entries. Each entry consists of an IP address (IPv4 or IPv6), the number of significant bits to test for, and the accept/reject policy for addresses matching the entry. Entries are tested in the order they were added to the filter. If an address matches an entry, its policy is used, and testing stops. If an address does not match any entry in the filter, the filter's default policy is used.
An IP filter is constructed in a struct ipfilter_t
object, which is opaque to the library user.
enum ipfilter_policy_t |
struct ipfilter_t* ipfilter_new | ( | void | ) |
Instantiate a new IP filter object.
This creates an empty filter, which will by default reject all incoming connections. Its policy may be changed with ipfilter_policy_set().
void ipfilter_free | ( | struct ipfilter_t * | ipf | ) |
Free an IP filter object.
ipf | IP filter object. May be 0. |
Frees all memory associated with an IP filter object.
enum ipfilter_policy_t ipfilter | ( | const struct ipfilter_t * | ipf, |
const struct sockaddr * | sa | ||
) |
Filter address.
ipf | IP filter object. |
sa | Address to filter. |
ipfilter_policy_accept | if address is accepted. |
ipfilter_policy_reject | if address is rejected. |
Filters the address sa (either struct sockaddr_in
or struct sockaddr_in6
for IPv4/IPv6 respectively) through the IP filter object ipf.
If sa is not an IP address but some other address family, ipfilter_policy_reject is returned.
enum ipfilter_policy_t ipfilter_policy_get | ( | const struct ipfilter_t * | ipf | ) |
Retrieve an IP filter's default accept/reject policy.
ipf | IP filter object. |
Returns the default accept/reject policy of the IP filter ipf.
void ipfilter_policy_set | ( | struct ipfilter_t * | ipf, |
enum ipfilter_policy_t | policy | ||
) |
Set an IP filter's default accept/reject policy.
ipf | IP filter object. |
policy | New accept/reject policy. |
Sets the default accept/reject policy of the IP filter ipf.
int ipfilter_add | ( | struct ipfilter_t * | ipf, |
const struct sockaddr * | sa, | ||
int | bits, | ||
enum ipfilter_policy_t | policy | ||
) |
Add an entry to an IP filter.
ipf | IP filter object. |
sa | Entry address. |
bits | Number of significant bits to test for. |
policy | Policy for matched addresses. |
0 | on success. |
-1 | on error (and see errno). |
This function adds an entry to the IP filter object ipf. The entry consists of an IP address (either struct sockaddr_in
or struct sockaddr_in6
for IPv4/IPv6 respectively), the number of significant bits in sa that will be tested, and the policy for matched addresses.
If sa does not point to an IPv4 or IPv6 address, errno is set to EAFNOSUPPORT
.
To match all addresses, it is legal to specify bits as 0. To match an IPv4 address exactly, bits should be 32. If it is outside the range 0–32 for an IPv4 address, the function will fail and set errno to EDOM
. Similarly, IPv6 addresses have 128 bits, and bits must be between 0–128.
int ipfilter_add_str | ( | struct ipfilter_t * | ipf, |
const char * | str, | ||
const char ** | endp | ||
) |
Add entry based on string.
ipf | IP filter object. | |
str | String to read entry from. | |
[out] | endp | Set to point to first character we stopped at. |
0 | on success. |
-1 | on error (and see errno). |
This function parses a string-based representation of an accept/reject entry, and adds the entry to the IP filter object ipf. It returns 0 on success and -1 on error. errno will be set as per ipfilter_add() or to EINVAL if the input string is not valid.
This function will skip leading or trailing whitespace. If the entry string is parsed successfully, endp will be set to the first non-whitespace character following the entry. If the entry string cannot be parsed, or ipfilter_add() fails, endp will be set to the first character that caused us to fail. endp may be 0 if this information is not required.
An entry string is formatted like this (case sensitive, no additional whitespace):
POLICY(ADDRESS[/NET])
POLICY
may either be accept
or reject
. ADDRESS
may be an IPv4 or IPv6 address in numerical notation, or a hostname to be resolved. If NET
and its leading slash is omitted, then the exact address (/32 for IPv4 or /128 for IPv6) will be used. If NET
is specified, it is the number of significant bits of the address to use.
Some examples:
accept(localhost)
— foo. accept(192.168.0.0/24)
— accept all IPv4 addresses on the 192.168.0.* subnet. accept(2001:41c8:1:5763::2/64)
— accept all IPv6 addresses with the 2001:41c8:1:5763 prefix. reject(0.0.0.0/0)
— reject all IPv4 addresses. reject(::/0)
— reject all IPv6 addresses. int ipfilter_add_commastr | ( | struct ipfilter_t * | ipf, |
const char * | str, | ||
const char ** | errp | ||
) |
Add entries based on comma-separated string.
ipf | IP filter object. |
str | String to read entries from. |
errp | Pointer to location at which error occurred. May be 0. |
0 | on success. |
-1 | on error (and see errno). |
This function parses a string with multiple IP filter entries separated by commas. Each entry is in the format specified by ipfilter_add_str(), and that function is used to parse each component of the string.
If all entries could be parsed, ipfilter_add_str() returns 0 and errp will point at the null terminating str. If any error occurs, -1 will be returned and errp will be set to point at the start of the first entry that failed. errp may be 0 if this information is not required.
Note that ipf may be changed even if an error occurs, as some of the filter string may have been parsed successfully.
void ipfilter_debug_dump | ( | const struct ipfilter_t * | ipf, |
char * | buf, | ||
int | sz | ||
) |
Dump IP filter to string for debugging.
ipf | IP filter object. |
buf | Pointer to buffer to dump to. |
sz | Size of buffer, in bytes. |
Dumps the contents of the IP filter object ipf to the string buf. buf will never be overrun and will always be null-terminated. The filter will be in the format described in ipfilter_add_commastr(), although any names will have been resolved to addresses.