1.. BSD LICENSE 2 Copyright(c) 2010-2014 Intel Corporation. All rights reserved. 3 All rights reserved. 4 5 Redistribution and use in source and binary forms, with or without 6 modification, are permitted provided that the following conditions 7 are met: 8 9 * Redistributions of source code must retain the above copyright 10 notice, this list of conditions and the following disclaimer. 11 * Redistributions in binary form must reproduce the above copyright 12 notice, this list of conditions and the following disclaimer in 13 the documentation and/or other materials provided with the 14 distribution. 15 * Neither the name of Intel Corporation nor the names of its 16 contributors may be used to endorse or promote products derived 17 from this software without specific prior written permission. 18 19 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 20 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 21 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 22 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 23 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 24 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 25 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 26 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 27 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 28 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 29 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 30 31Packet Classification and Access Control 32======================================== 33 34The DPDK provides an Access Control library that gives the ability 35to classify an input packet based on a set of classification rules. 36 37The ACL library is used to perform an N-tuple search over a set of rules with multiple categories 38and find the best match (highest priority) for each category. 39The library API provides the following basic operations: 40 41* Create a new Access Control (AC) context. 42 43* Add rules into the context. 44 45* For all rules in the context, build the runtime structures necessary to perform packet classification. 46 47* Perform input packet classifications. 48 49* Destroy an AC context and its runtime structures and free the associated memory. 50 51Overview 52-------- 53 54The current implementation allows the user for each AC context to specify its own rule (set of fields) 55over which packet classification will be performed. 56To define each field inside an AC rule, the following structure is used: 57 58.. code-block:: c 59 60 struct rte_acl_field_def { 61 uint8_t type; /*< type - ACL_FIELD_TYPE. */ 62 uint8_t size; /*< size of field 1,2,4, or 8. */ 63 uint8_t field_index; /*< index of field inside the rule. */ 64 uint8_t input_index; /*< 0-N input index. */ 65 uint32_t offset; /*< offset to start of field. */ 66 }; 67 68* type 69 The field type is one of three choices: 70 71 * _MASK - for fields such as IP addresses that have a value and a mask defining the number of relevant bits. 72 73 * _RANGE - for fields such as ports that have a lower and upper value for the field. 74 75 * _BITMASK - for fields such as protocol identifiers that have a value and a bit mask. 76 77* size 78 The size parameter defines the length of the field in bytes. Allowable values are 1, 2, 4, or 8 bytes. 79 Note that due to the grouping of input bytes, 1 or 2 byte fields must be defined as consecutive fields 80 that make up 4 consecutive input bytes. 81 Also, it is best to define fields of 8 or more bytes as 4 byte fields so that 82 the build processes can eliminate fields that are all wild. 83 84* field_index 85 A zero-based value that represents the position of the field inside the rule; 0 to N-1 for N fields. 86 87* input_index 88 For performance reasons, the inner loop of the search function is unrolled to process four input bytes at a time. 89 This requires the input to be grouped into sets of 4 consecutive bytes. 90 The loop processes the first input byte as part of the setup and then 91 subsequent bytes must be in groups of 4 consecutive bytes. 92 The input index specifies to which input group that field belongs to. 93 94* offset 95 The offset field defines the offset for the field. 96 This is the offset from the beginning of the buffer parameter for the search. 97 98For example, to define classification for the following IPv4 5-tuple structure: 99 100.. code-block:: c 101 102 struct ipv4_5tuple { 103 uint8_t proto; 104 uint32_t ip_src; 105 uint32_t ip_dst; 106 uint16_t port_src; 107 uint16_t port_dst; 108 }; 109 110The following array of field definitions can be used: 111 112.. code-block:: c 113 114 struct rte_acl_field_def ipv4_defs[5] = { 115 /* first input field - always one byte long. */ 116 { 117 .type = RTE_ACL_FIELD_TYPE_BITMASK, 118 .size = sizeof (uint8_t), 119 .field_index = 0, 120 .input_index = 0, 121 .offset = offsetof (struct ipv4_5tuple, proto), 122 }, 123 124 /* next input field (IPv4 source address) - 4 consecutive bytes. */ 125 { 126 .type = RTE_ACL_FIELD_TYPE_MASK, 127 .size = sizeof (uint32_t), 128 .field_index = 1, 129 .input_index = 1, 130 .offset = offsetof (struct ipv4_5tuple, ip_src), 131 }, 132 133 /* next input field (IPv4 destination address) - 4 consecutive bytes. */ 134 { 135 .type = RTE_ACL_FIELD_TYPE_MASK, 136 .size = sizeof (uint32_t), 137 .field_index = 2, 138 .input_index = 2, 139 .offset = offsetof (struct ipv4_5tuple, ip_dst), 140 }, 141 142 /* 143 * Next 2 fields (src & dst ports) form 4 consecutive bytes. 144 * They share the same input index. 145 */ 146 { 147 .type = RTE_ACL_FIELD_TYPE_RANGE, 148 .size = sizeof (uint16_t), 149 .field_index = 3, 150 .input_index = 3, 151 .offset = offsetof (struct ipv4_5tuple, port_src), 152 }, 153 154 { 155 .type = RTE_ACL_FIELD_TYPE_RANGE, 156 .size = sizeof (uint16_t), 157 .field_index = 4, 158 .input_index = 3, 159 .offset = offsetof (struct ipv4_5tuple, port_dst), 160 }, 161 }; 162 163A typical example of such an IPv4 5-tuple rule is a follows: 164 165:: 166 167 source addr/mask destination addr/mask source ports dest ports protocol/mask 168 192.168.1.0/24 192.168.2.31/32 0:65535 1234:1234 17/0xff 169 170Any IPv4 packets with protocol ID 17 (UDP), source address 192.168.1.[0-255], destination address 192.168.2.31, 171source port [0-65535] and destination port 1234 matches the above rule. 172 173To define classification for the IPv6 2-tuple: <protocol, IPv6 source address> over the following IPv6 header structure: 174 175.. code-block:: c 176 177 struct struct ipv6_hdr { 178 uint32_t vtc_flow; /* IP version, traffic class & flow label. */ 179 uint16_t payload_len; /* IP packet length - includes sizeof(ip_header). */ 180 uint8_t proto; /* Protocol, next header. */ 181 uint8_t hop_limits; /* Hop limits. */ 182 uint8_t src_addr[16]; /* IP address of source host. */ 183 uint8_t dst_addr[16]; /* IP address of destination host(s). */ 184 } __attribute__((__packed__)); 185 186The following array of field definitions can be used: 187 188.. code-block:: c 189 190 struct struct rte_acl_field_def ipv6_2tuple_defs[5] = { 191 { 192 .type = RTE_ACL_FIELD_TYPE_BITMASK, 193 .size = sizeof (uint8_t), 194 .field_index = 0, 195 .input_index = 0, 196 .offset = offsetof (struct ipv6_hdr, proto), 197 }, 198 199 { 200 .type = RTE_ACL_FIELD_TYPE_MASK, 201 .size = sizeof (uint32_t), 202 .field_index = 1, 203 .input_index = 1, 204 .offset = offsetof (struct ipv6_hdr, src_addr[0]), 205 }, 206 207 { 208 .type = RTE_ACL_FIELD_TYPE_MASK, 209 .size = sizeof (uint32_t), 210 .field_index = 2, 211 .input_index = 2, 212 .offset = offsetof (struct ipv6_hdr, src_addr[4]), 213 }, 214 215 { 216 .type = RTE_ACL_FIELD_TYPE_MASK, 217 .size = sizeof (uint32_t), 218 .field_index = 3, 219 .input_index = 3, 220 .offset = offsetof (struct ipv6_hdr, src_addr[8]), 221 }, 222 223 { 224 .type = RTE_ACL_FIELD_TYPE_MASK, 225 .size = sizeof (uint32_t), 226 .field_index = 4, 227 .input_index = 4, 228 .offset = offsetof (struct ipv6_hdr, src_addr[12]), 229 }, 230 }; 231 232A typical example of such an IPv6 2-tuple rule is a follows: 233 234:: 235 236 source addr/mask protocol/mask 237 2001:db8:1234:0000:0000:0000:0000:0000/48 6/0xff 238 239Any IPv6 packets with protocol ID 6 (TCP), and source address inside the range 240[2001:db8:1234:0000:0000:0000:0000:0000 - 2001:db8:1234:ffff:ffff:ffff:ffff:ffff] matches the above rule. 241 242When creating a set of rules, for each rule, additional information must be supplied also: 243 244* **priority**: A weight to measure the priority of the rules (higher is better). 245 If the input tuple matches more than one rule, then the rule with the higher priority is returned. 246 Note that if the input tuple matches more than one rule and these rules have equal priority, 247 it is undefined which rule is returned as a match. 248 It is recommended to assign a unique priority for each rule. 249 250* **category_mask**: Each rule uses a bit mask value to select the relevant category(s) for the rule. 251 When a lookup is performed, the result for each category is returned. 252 This effectively provides a "parallel lookup" by enabling a single search to return multiple results if, 253 for example, there were four different sets of ACL rules, one for access control, one for routing, and so on. 254 Each set could be assigned its own category and by combining them into a single database, 255 one lookup returns a result for each of the four sets. 256 257* **userdata**: A user-defined field that could be any value except zero. 258 For each category, a successful match returns the userdata field of the highest priority matched rule. 259 260.. note:: 261 262 When adding new rules into an ACL context, all fields must be in host byte order (LSB). 263 When the search is performed for an input tuple, all fields in that tuple must be in network byte order (MSB). 264 265Application Programming Interface (API) Usage 266--------------------------------------------- 267 268.. note:: 269 270 For more details about the Access Control API, please refer to the *DPDK API Reference*. 271 272The following example demonstrates IPv4, 5-tuple classification for rules defined above 273with multiple categories in more detail. 274 275Classify with Multiple Categories 276~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 277 278.. code-block:: c 279 280 struct rte_acl_ctx * acx; 281 struct rte_acl_config cfg; 282 int ret; 283 284 /* define a structure for the rule with up to 5 fields. */ 285 286 RTE_ACL_RULE_DEF(acl_ipv4_rule, RTE_DIM(ipv4_defs)); 287 288 /* AC context creation parameters. */ 289 290 struct rte_acl_param prm = { 291 .name = "ACL_example", 292 .socket_id = SOCKET_ID_ANY, 293 .rule_size = RTE_ACL_RULE_SZ(RTE_DIM(ipv4_defs)), 294 295 /* number of fields per rule. */ 296 297 .max_rule_num = 8, /* maximum number of rules in the AC context. */ 298 }; 299 300 struct acl_ipv4_rule acl_rules[] = { 301 302 /* matches all packets traveling to 192.168.0.0/16, applies for categories: 0,1 */ 303 { 304 .data = {.userdata = 1, .category_mask = 3, .priority = 1}, 305 306 /* destination IPv4 */ 307 .field[2] = {.value.u32 = IPv4(192,168,0,0),. mask_range.u32 = 16,}, 308 309 /* source port */ 310 .field[3] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 311 312 /* destination port */ 313 .field[4] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 314 }, 315 316 /* matches all packets traveling to 192.168.1.0/24, applies for categories: 0 */ 317 { 318 .data = {.userdata = 2, .category_mask = 1, .priority = 2}, 319 320 /* destination IPv4 */ 321 .field[2] = {.value.u32 = IPv4(192,168,1,0),. mask_range.u32 = 24,}, 322 323 /* source port */ 324 .field[3] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 325 326 /* destination port */ 327 .field[4] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 328 }, 329 330 /* matches all packets traveling from 10.1.1.1, applies for categories: 1 */ 331 { 332 .data = {.userdata = 3, .category_mask = 2, .priority = 3}, 333 334 /* source IPv4 */ 335 .field[1] = {.value.u32 = IPv4(10,1,1,1),. mask_range.u32 = 32,}, 336 337 /* source port */ 338 .field[3] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 339 340 /* destination port */ 341 .field[4] = {.value.u16 = 0, .mask_range.u16 = 0xffff,}, 342 }, 343 344 }; 345 346 347 /* create an empty AC context */ 348 349 if ((acx = rte_acl_create(&prm)) == NULL) { 350 351 /* handle context create failure. */ 352 353 } 354 355 /* add rules to the context */ 356 357 ret = rte_acl_add_rules(acx, acl_rules, RTE_DIM(acl_rules)); 358 if (ret != 0) { 359 /* handle error at adding ACL rules. */ 360 } 361 362 /* prepare AC build config. */ 363 364 cfg.num_categories = 2; 365 cfg.num_fields = RTE_DIM(ipv4_defs); 366 367 memcpy(cfg.defs, ipv4_defs, sizeof (ipv4_defs)); 368 369 /* build the runtime structures for added rules, with 2 categories. */ 370 371 ret = rte_acl_build(acx, &cfg); 372 if (ret != 0) { 373 /* handle error at build runtime structures for ACL context. */ 374 } 375 376For a tuple with source IP address: 10.1.1.1 and destination IP address: 192.168.1.15, 377once the following lines are executed: 378 379.. code-block:: c 380 381 uint32_t results[4]; /* make classify for 4 categories. */ 382 383 rte_acl_classify(acx, data, results, 1, 4); 384 385then the results[] array contains: 386 387.. code-block:: c 388 389 results[4] = {2, 3, 0, 0}; 390 391* For category 0, both rules 1 and 2 match, but rule 2 has higher priority, 392 therefore results[0] contains the userdata for rule 2. 393 394* For category 1, both rules 1 and 3 match, but rule 3 has higher priority, 395 therefore results[1] contains the userdata for rule 3. 396 397* For categories 2 and 3, there are no matches, so results[2] and results[3] contain zero, 398 which indicates that no matches were found for those categories. 399 400For a tuple with source IP address: 192.168.1.1 and destination IP address: 192.168.2.11, 401once the following lines are executed: 402 403.. code-block:: c 404 405 uint32_t results[4]; /* make classify by 4 categories. */ 406 407 rte_acl_classify(acx, data, results, 1, 4); 408 409the results[] array contains: 410 411.. code-block:: c 412 413 results[4] = {1, 1, 0, 0}; 414 415* For categories 0 and 1, only rule 1 matches. 416 417* For categories 2 and 3, there are no matches. 418 419For a tuple with source IP address: 10.1.1.1 and destination IP address: 201.212.111.12, 420once the following lines are executed: 421 422.. code-block:: c 423 424 uint32_t results[4]; /* make classify by 4 categories. */ 425 rte_acl_classify(acx, data, results, 1, 4); 426 427the results[] array contains: 428 429.. code-block:: c 430 431 results[4] = {0, 3, 0, 0}; 432 433* For category 1, only rule 3 matches. 434 435* For categories 0, 2 and 3, there are no matches. 436