| Netra Data Plane Software Suite 2.0 Update 2 Reference Manual |    
|
| C H A P T E R 8 |
|
Access Control List Library API |
This chapter describes the Access Control List (ACL) library API. Topics include:
The Access Control List (ACL) library for Netra DPS classifies IPv4 packets using a set of rules.
The classification can be done using the source/destination addresses and ports as well as the protocol and the priority of the packet.
The algorithms are used in the library trade memory for speed; the rules are preprocessed to achieve high lookup rate while using a lot of memory.
The ACL library uses various algorithms to classify the packets.
This algorithm finds the Longest Matching Prefixes of the source and destination addresses and searches for the highest priority rule among all those rules matching the particular prefix pair. The Longest Matching Prefixes algorithm can use either Binary Search on Prefix Lengths (BSPL) or TRIE lookup (see “TRIE” below).
This algorithm is well suited for rulesets with a large number of rules (millions) where only a few rules (dozens) remain after the prefix lookups. The data structures can be updated quickly, allowing to add or remove thousands of rules each second. The initial rule insertion is even faster, that is, millions of rules can be added in a few seconds.
Binary Search on Prefix Lengths (BSPL) works by finding the longest matching prefix of an address by doing binary search on prefix length, that is, starting in the hash table containing median length prefixes and continuing in a hash table with longer prefixes if a match is found, shorter prefixes otherwise.
The TRIE (retrieval) algorithm uses a three-level prefix tree to find the longest matching prefix of an address.
The ACL library also contains a reference implementation of the HiCut lookup algorithm.
This algorithm can do very fast lookups regardless of the distribution of the rules, but cannot use as many rules as the hybrid algorithm because the insertion time increases exponentially by the number of rules. Moreover, there is no way to update the ruleset, the data structures have to be rebuilt completely after adding new rules.
The ACL functions use a pointer to a data structure which contains all data necessary to change the ruleset or match packets against them. This allows changing the rulesets without disturbing the packet classification: by having two datasets and using one of them to classify packets while applying changes to the other. Once the changes are made the datasets can be swapped without affecting lookup performance, that is, no locks are necessary.
The ACL data structures can be copied to a new buffer or remapped to a new address without breaking the lookup algorithm. The ACL data structures allows preparing them in a domain and using them in another, that is, rule management and packet classification can be done in separate domains if required.
Data types consist of packet and rule types.
The packets used by the ACL library are standard TCP/UDP over IPv4 packets.
A rule consists of six fields to match against TCP/IP packets:
The rule also contains a classification value (color) which is returned by the lookup algorithm when the packet matches the rule. The rules are ordered by the color in ascending order: the lookup returns the color of the lowest-color matching rule.
Initialization routine for the ACL. Based on the selected algorithm it fills up the given buffer with data necessary to insert and remove rules and lookup packets, that is, the caller has to allocate a buffer and pass it to acl_init and subsequent acl_* calls.
Error code is written in the provided variable.
void *acl_init(void *buf, size_t size, int alg, int *error);
buf - Pointer to the buffer to be filled with initialized data
alg - Algorithm selector (see Algorithms), in short: ACL_ALG_HYBRID_BSPL - Hybrid algorithm, LPM is using BSPL ACL_ALG_HYBRID_TRIE - Hybrid algorithm, LPM is using trie ACL_ALG_HICUT - HiCut
error - Pointer to a variable where the error code is to be written
On success, it returns a pointer to the initialized ACL data or NULL in case of error. The error code is returned in “error”.
Takes the rules from the given array and inserts them into the pre-initialized data structures, performs the necessary preprocessing and optimization, leaving the dataset ready to be used for packet lookup.
int acl_insert(void *acl, rule_t *rule, int num);
acl - Pointer to the initialized ACL data
rule - Pointer to the first rule in the array
num - Number of rules in the rule array
On success, it returns zero, or an error code in case of error.
Takes rules from the given array and removes each of them from the data structures.
int acl_remove(void *acl, rule_t *rule, int num);
acl - Pointer to the initialized ACL data
rule - Pointer to the first rule in the array
num - Number of rules in the rule array
On success, it returns zero, or an error code in case of error.
Matches the packet against the rules and returns the classification value.
color_t acl_lookup(void *acl, packet_t *packet);
acl - Pointer to the initialized ACL data
packet - Pointer to the packet to be processed
Returns the color of the lowest-color matching rule or the default color value if none of the rules matches the packet.
Lists the current ruleset. Copies rules into the provided array.
int acl_list(void *buf, rule_t *rule, int num);
buf - Pointer to the initialized ACL data
rule - Array of rules to copy to
num - Maximum number of rules to copy
On success return the number of rules. If there are more rules to list than the provided array can store, then return (-num).
ACL_INIT_OK - Initialization was successful
ACL_INIT_FAILED - Initialization has failed
ACL_INIT_UNKNOWN_ALG - Invalid algorithm was passed ACL_INIT_MEMORY_ERROR - Buffer size is too small
ACL_INVALID_MAGIC - Corrupted data in ACL buffer
| Netra Data Plane Software Suite 2.0 Update 2 Reference Manual | 820-5212-11 |
|
Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.