Key Test

SmartNIC Filtering with Link-Capture™ Software
Platform
Napatech SmartNIC
Content Type
User Guide
Capture Software Version
Link™ Capture Software 12.11

A maximum of two independent key tests per frame can be performed.

Single access

If only one key test per frame is defined, Access=Single is used in the KeyType command.

Fields for a single-access key test can be defined with the following constraints.
  • A maximum of 320 bits are allowed.
  • The 320-bit data can consist of 4 blocks: Two 128-bit fields and two 32-bit fields as shown in the following figure.
    Page-1 Sheet.53 Sheet.45 Ethernet frame Ethernet frame Sheet.46 Sheet.47 Sheet.54 Sheet.55 Sheet.56 Field1 Field1 Sheet.57 Field2 Field2 Sheet.58 Field3 Field3 Sheet.59 Field4 Field4 Sheet.60 Extracted data Extracted data Sheet.63 Dynamic connector Sheet.64 128 bits 128 bits Sheet.66 128 bits 128 bits Sheet.67 32 bits 32 bits Sheet.68 32 bits 32 bits

  • For an exact key match (a value without a mask in KeyLists), the length of the fields can be a maximum of 192 bits.
  • For a wild card match (a value with masks in KeyLists), the length of the fields can be a maximum of 320 bits.
The following NTPL example configures the SmartNIC to observe the outer IPv6 header and the inner IPv4 header of tunneled traffic.
// Define fields for key match.
Define IPv6SrcField = Field(Layer3Header[8]/128)
Define IPv6DstField = Field(Layer3Header[24]/128)
Define InnerIPv4Src = Field(InnerLayer3Header[12]/32)
Define InnerIpv4Dst = Field(InnerLayer3Header[16]/32)

// Define a filter for GTP-U IPv6 traffic containing inner IPv4.  
Define isIPv6_containing_IPv4 = Filter(TunnelType==GTPv1-U \\
and Layer3Protocol==IPv6 and InnerLayer3Protocol==IPv4)

// Define a KeySet identifier.
Define A_list = Macro("3")

KeyType[name=KT_4tuple; ColorInfo=True; Access=Single] = {128, 128, 32, 32}

KeyDef[name=OuterIPv6_innerIPv4; KeyType=KT_4tuple] = (IPv6SrcField, IPv6DstField, InnerIPv4Src, InnerIpv4Dst)

Assign[StreamId=0; Descriptor=DYN2] = isIPv6_containing_IPv4 and Key(OuterIPv6_innerIPv4)==A_list

KeyList[KeySet = A_list ; Color=100; KeyType=KT_4tuple] = \\
( {[ffff:ffff:ffff:ffff:ffff:ffff:ffff:0000]:[d7a0:4e95:0:0:0:0:af:0000]}, \\
{[ffff:ffff:ffff:ffff:ffff:ffff:ffff:0000]:[91:92:0:0:0:0:93:94]}, \\
{[ff.ff.ff.00]:[192.168.0.2]}, {[ff.ff.ff.00]:[10.100.1.2]} )
Access=Single can be omitted as it is set by default.

Full access and partial access

The SmartNIC can perform a maximum of two independent key tests per frame as shown in the following example.
// Define fields for inner source/destination IPv6 addresses.
Define InnerIPv6SrcField = Field(InnerLayer3Header[8]/128)
Define InnerIPv6DstField = Field(InnerLayer3Header[24]/128)

// Define a filter for GTP-U traffic with inner IPV6.
Define isInnerIPv6 = Filter(TunnelType==GTPv1-U and InnerLayer3Protocol==IPv6)

KeyType[Name=KT_IPv6; ColorInfo=True; Access=Full] = {128}

KeyDef[Name=InnerSrcIPv6; KeyType=KT_IPv6] = (InnerIPv6SrcField)
KeyDef[Name=InnerDstIPv6; KeyType=KT_IPv6] = (InnerIPv6DstField)

Assign[StreamId=0; Descriptor=DYN2] = isInnerIPv6 AND (Key(InnerSrcIPv6)==3 AND Key(InnerDstIPv6)==4)

KeyList[KeySet=3; KeyType=KT_IPv6; Color=23] = ([1234:abcd:0:0:0:0:0:c0ed])
KeyList[KeySet=4; KeyType=KT_IPv6; Color=24] = ([d7a0:4e95:0:0:0:0:af:0000])
This NTPL example sets a filter to capture GTP-U traffic which contains IPv6 in the inner layer. One key test is done on the inner source IPv6 address field, and another key test is done on the inner destination IPv6 address field. Two KeyDefs (InnerSrcIPv6 and InnerDstIPv6) are configured to perform two key tests.
The fields for two key tests can be defined under constraints as follows.
  • A maximum of 320 bits for two key tests are allowed.
  • The 320-bit data consist of 4 blocks: Two 128-bit fields and two 32-bit fields of a frame as follows.
    Page-1 Sheet.53 Sheet.45 Ethernet frame Ethernet frame Sheet.46 Sheet.47 Sheet.54 Sheet.55 Sheet.56 Field1 Field1 Sheet.57 Field2 Field2 Sheet.58 Field3 Field3 Sheet.59 Field4 Field4 Sheet.60 Extracted data Extracted data Sheet.63 Dynamic connector Sheet.64 128 bits 128 bits Sheet.66 128 bits 128 bits Sheet.67 32 bits 32 bits Sheet.68 32 bits 32 bits

  • If the same KeyType is used for both key tests, a maximum of 160 bits can be selected. Access=Full must be set. This figure shows an example of Access=Full.
    Page-1 Sheet.48 Fields for the first key test Fields for the first key test Sheet.59 Sheet.60 Sheet.61 Sheet.62 Sheet.63 128 bits 128 bits Sheet.64 32 bits 32 bits Sheet.65 128 bits 128 bits Sheet.66 32 bits 32 bits Sheet.67 Fields for the second key test Fields for the second key test

  • If two different KeyTypes are used, one KeyType can be a maximum of 320 bits, and another KeyType can be a maximum of 160 bits. Some fields for two KeyDefs can be duplicated. Access=Partial must be set. This figure shows an example of Access=Partial.
    Page-1 Sheet.68 Fields for the first key test Fields for the first key test Sheet.77 Fields for the second key test Fields for the second key test Sheet.78 Sheet.79 Sheet.80 Sheet.81 Sheet.82 128 bits 128 bits Sheet.83 128 bits 128 bits Sheet.84 32 bits 32 bits Sheet.85 32 bits 32 bits

  • For an exact key match (a value without a mask in the KeyList commands), the length of the fields can be a maximum of 192 bits for one key test and a maximum of 160 bits for another key test.
  • For a wild card match (a value with masks in the KeyList commands), the length of the fields for one key test + the length of the fields for another key test can be a maximum of 384 bits.
In the following NTPL example, two KeyTypes are configured for two key tests. As the KeyType of each KeyDef is different, Access=Partial is configured in the KeyType commands. 
// Define a filter to capture IPv4 carrying TCP.
Define isIPv4_TCP = Filter(Layer3Protocol==IPv4 and Layer4Protocol==TCP)

KeyType[Name=KT_IP; Access=Partial; Bank=0] = {32}
KeyType[Name=KT_Port; Access=Partial; Bank=1] = {16}

KeyDef[Name=SrcIPv4; KeyType=KT_IP] = (Layer3Header[12]/32) 
KeyDef[Name=SrcPort; KeyType=KT_Port] = (Layer4Header[0]/16) 

// Match IPv4 in keyset 3 and TCP port in key set 4.
Assign[StreamId=0] = isIPv4_TCP AND (Key(SrcIPv4)==3 OR Key(SrcPort)==4)

KeyList[KeyType=KT_IP; KeySet=3] = ( [192.168.0.2] ),( {[ff.ff.ff.00]:[192.168.1.2]} )
KeyList[KeyType=KT_Port; KeySet=4] = ( 80 )
Bank=0 must be configured in one KeyType command, and Bank=1 must be configured in another KeyType command when Access=Partial is used. The CAM consists of two banks, and the Bank parameter determines which bank to be used for storing values of the corresponding KeyType. See CAM and TCAM for more information on the CAM and the TCAM.

Any keyword

In the following NTPL example, two Assign commands are used to apply two different hashing (HashUp and HashDown) based on either source or destination IPv6 addresses. As the same filter (isIPv6) is applied for both lines, the second Assign command overrules the first Assign command.
Note: When the Assign commands are evaluated, only the filter module (isIPv6) is counted, not the key match module.
Note: When multiple Assign commands are defined, the last one gets the highest priority unless the priority is explicitly configured.
// Define IPv6 source and destination fields.
Define IPv6SrcField = Field(Layer3Header[8]/128)
Define IPv6DstField = Field(Layer3Header[24]/128)

// Define a IPv6 protocol filter.
Define isIPv6 = Filter(Layer3Protocol==IPv6)

// Define a hash mode for upstream traffic.
Define HashUp = Hash(HashWord0_3=IPv6SrcField)

// Define another hash mode for downstream traffic.
Define HashDown = Hash(HashWord0_3=IPv6DstField)

KeyType[name=KT; ColorInfo=True] = {128}
KeyDef[name=SrcIPv6; KeyType=KT] = (IPv6SrcField)
KeyDef[name=DstIPv6; KeyType=KT] = (IPv6DstField)

Assign[StreamId=(0..31); Hash=HashUp; Descriptor=DYN2] =  isIPv6 AND (Key(SrcIPv6)==8)
Assign[StreamId=(0..31); Hash=HashDown; Descriptor=DYN2] = isIPv6 AND (Key(DstIPv6)==8)

KeyList[KeySet = 8; Color=100; KeyType=KT] = ([d7a0:4e95:0:0:0:0:af:0000]), \\
([91:92:0:0:0:0:93:94])

The first Assign command will not have any effect. This means that key tests will be performed on the destination IPv6 address field only. As a result, IPv6 frames with the given IPv6 addresses on the source address field will not be delivered to the host. To solve this issue, the Assign commands can be configured as follows.

Define IPv6SrcField = Field(Layer3Header[8]/128)
Define IPv6DstField = Field(Layer3Header[24]/128)
Define isIPv6 = Filter(Layer3Protocol == IPv6)
Define HashUp = Hash(HashWord0_3=IPv6SrcField)
Define HashDown = Hash(HashWord0_3=IPv6DstField)

KeyType[name=KT; ColorInfo=True; Access=Full] = {128}
KeyDef[name=SrcIPv6; KeyType=KT] = (IPv6SrcField)
KeyDef[name=DstIPv6; KeyType=KT] = (IPv6DstField)

Assign[StreamId=(0..31); Hash=HashUp; Descriptor=DYN2] =  isIPv6 AND (Key(SrcIPv6)==8 AND Key(DstIPv6)==ANY)
Assign[StreamId=(0..31); Hash=HashDown; Descriptor=DYN2] = isIPv6 AND (Key(SrcIPv6)==ANY AND Key(DstIPv6)==8)

KeyList[KeySet = 8; Color=100; KeyType=KT] = ([d7a0:4e95:0:0:0:0:af:0000]), ([91:92:0:0:0:0:93:94])

Additional key test with the ANY keyword is added to each Assign command which is always evaluated to true. This is done to perform the key tests on both SrcIPv6 and DstIPv6 for each frame. Therefore, both destination and source IPv6 address fields will be searched. As a result, frames with given IP addresses either on the source IPv6 address field or on the destination IPv6 address field will be delivered to the host.

Note: If the same hash mode is applied to received frames regardless of upstream or downstream traffic, one Assign command can be configured as follows.
Define IPv6SrcField = Field(Layer3Header[8]/128)
Define IPv6DstField = Field(Layer3Header[24]/128)
Define isIPv6 = Filter(Layer3Protocol == IPv6)
HashMode=Hash2TupleSorted

KeyType[name=KT; ColorInfo=True; Access=Full] = {128}
KeyDef[name=SrcIPv6; KeyType=KT] = (IPv6SrcField)
KeyDef[name=DstIPv6; KeyType=KT] = (IPv6DstField)

Assign[StreamId=(0..31); Descriptor=DYN2] = isIPv6 AND (Key(SrcIPv6)==8 OR Key(DstIPv6)==8)

KeyList[KeySet=8; Color=100; KeyType=KT] = ([d7a0:4e95:0:0:0:0:af:0000]), \\
([91:92:0:0:0:0:93:94])

CAM and TCAM

A value for an exact key search (a value without a mask in the KeyList command) is stored in the content-addressable memory (CAM), and a value for a wild card search (a value with masks) is stored in the ternary content-addressable memory (TCAM). Some exceptions are applied as follows:
  • If the CAM is full and the TCAM is available, the SmartNIC attempts to store values for an exact match in the TCAM.
  • If a value for an exact key match has a length greater than the specified limit, the SmartNIC attempts to store the value in the TCAM (if available).
Note: The following error message may be generated with values for an exact search in the KeyList command due to this underlying process for storing values in the CAM and the TCAM.
>>> Not enough TCAM resources to store the Key type

The CAM can store a maximum of 36,000 IPv4-address-size entries or a maximum of 8,000 IPv6-address-size entries. The TCAM can store a maximum of 864 IPv4-address-size entries or a maximum of 216 IPv6-address-size entries.

TCAM bank structure

The TCAM consists of 12 banks. Each bank can contain 72 entries of a 32-bit value as shown in this figure.

Page-1 5 ruled column Entry 1 Entry 2 ... ... Entry72 Entry 1 Entry 2......Entry72 5 ruled column.6 5 ruled column.7 5 ruled column.8 5 ruled column.9 5 ruled column.10 5 ruled column.11 5 ruled column.12 5 ruled column.13 5 ruled column.14 5 ruled column.15 5 ruled column.16 Sheet.49 32 bits 32 bits Dynamic connector Sheet.88 384 bits 384 bits Dynamic connector.89 Sheet.114 Bank 1 Bank 1 Sheet.115 2 2 Sheet.116 3 3 Sheet.117 4 4 Sheet.118 5 5 Sheet.119 6 6 Sheet.120 7 7 Sheet.121 8 8 Sheet.122 9 9 Sheet.123 10 10 Sheet.124 11 11 Sheet.125 12 12

For example, if values are 32-bit IPv4 addresses, 72 IPv4 addresses can be stored in one bank.

Banks are coupled to store values with larger lengths. For example, 4 banks are coupled to store IPv6 addresses (128 bits) as shown in the following figure.

Page-1 5 ruled column.21 IPv6 1 IPv6 2 ... ... IPv6 72 IPv6 1IPv6 2......IPv6 72 5 ruled column.25 5 ruled column.29 5 ruled column.30 5 ruled column.31 5 ruled column.32 Sheet.52 128 bits 128 bits Dynamic connector.53 Sheet.126 Bank 1 Bank 1 Sheet.127 2 2 Sheet.128 3 3 Sheet.129 4 4 Sheet.130 5 5 Sheet.131 6 6 Sheet.132 7 7 Sheet.133 8 8 Sheet.134 9 9 Sheet.135 10 10 Sheet.136 11 11 Sheet.137 12 12

If two key tests per frame are configured, banks are split in two. If the length of values for both key tests are the same, 6 banks are available for each key test. Therefore, a maximum of 192 bits can be used to store each entry as 6 banks are coupled.

Page-1 5 ruled column.54 IPv4 1 IPv4 2 ... ... IPv4 72 IPv4 1 IPv4 2......IPv4 72 5 ruled column.55 5 ruled column.56 5 ruled column.57 5 ruled column.58 5 ruled column.59 5 ruled column.60 5 ruled column.61 5 ruled column.62 5 ruled column.63 5 ruled column.64 5 ruled column.65 Sheet.90 192 bits 192 bits Sheet.92 32 bits 32 bits Dynamic connector.93 Dynamic connector.94 Sheet.95 TCAM banks for key test 1 TCAM banks for key test 1 Sheet.112 TCAM banks for key test 2 TCAM banks for key test 2 Sheet.138 Bank 1 Bank 1 Sheet.139 2 2 Sheet.140 3 3 Sheet.141 4 4 Sheet.142 5 5 Sheet.143 6 6 Sheet.144 7 7 Sheet.145 8 8 Sheet.146 9 9 Sheet.147 10 10 Sheet.148 11 11 Sheet.149 12 12

In the following example, 8 banks are used to store values for one key test, and 4 banks are used to store values for another key test.
Page-1 5 ruled column.67 IPv6 src 1 IPv6 src 2 ... ... IPv6 src 72 IPv6 src 1IPv6 src 2......IPv6 src 72 5 ruled column.68 IPv6 dst 1 IPv6 dst 2 ... ... IPv6 dst 72 IPv6 dst 1IPv6 dst 2......IPv6 dst 72 5 ruled column.69 5 ruled column.70 5 ruled column.71 IPv4 1 IPv4 2 ... ... IPv4 72 IPv4 1 IPv4 2......IPv4 72 5 ruled column.72 Sheet.76 128 bits 128 bits Dynamic connector.77 Sheet.100 TCAM banks for key test 1 TCAM banks for key test 1 Sheet.106 32 bits 32 bits Dynamic connector.107 Sheet.110 256 bits 256 bits Dynamic connector.111 Sheet.150 Bank 1 Bank 1 Sheet.151 2 2 Sheet.152 3 3 Sheet.153 4 4 Sheet.154 5 5 Sheet.155 6 6 Sheet.156 7 7 Sheet.157 8 8 Sheet.158 9 9 Sheet.159 10 10 Sheet.160 11 11 Sheet.161 12 12 Sheet.162 TCAM banks for key test 2 TCAM banks for key test 2

Note: The following error message may be generated if the length of the fields exceeds the specified limit in the bank structure for storing values in the TCAM.
>>> Not enough TCAM resources to store the Key type

Using a mask in KeyDef

In the following example, a subnet mask is configured for individual IP addresses in the KeyList commands.
// Macros for KeySet identifiers.
Define IP_list0 = Macro("3")
Define IP_list1 = Macro("4")

// IPv4 protocol filter.
Define isIPv4 = Filter(Layer3Protocol == IPv4)
// Source IPv4 field.
Define IPv4SrcField = Field(Layer3Header[12]/32)

KeyType[Name=KT_IPv4] = {32}
KeyDef[Name=IPv4Src; KeyType=KT_IPv4] = (IPv4SrcField)

Assign[StreamId=0] = isIPv4 AND Key(IPv4Src)==IP_list0
Assign[StreamId=1] = isIPv4 AND Key(IPv4Src)==IP_list1

KeyList[KeySet=IP_list0; KeyType=KT_IPv4] = ( {[ff.ff.ff.00]:[192.168.0.0]} ),\\
( {[ff.ff.ff.00]:[192.168.1.0]} )

KeyList[KeySet=IP_list1; KeyType=KT_IPv4] = ( {[ff.ff.ff.00]:[192.168.2.0]} ),\\
( {[ff.ff.ff.00]:[192.168.3.0]} )
Using this example, the SmartNIC delivers frames to stream 0 if the IP address is contained in the subnet of 192.168.0.0 or 192.168.1.0. The second Assign command indicates that frames are delivered to stream 1 if the IP address is contained in the subnet of 192.168.2.0 or 192.168.3.0.
The same results can be obtained if the KeyDef and KeyList commands are defined as follows. 
KeyDef[Name=IPv4Src; KeyType=KT_IPv4] = ( {[ff.ff.ff.00]:IPv4SrcField} )

KeyList[KeySet = IP_list0; KeyType=KT_IPv4] = ( [192.168.0.0] ),( [192.168.1.0] ) 
KeyList[KeySet = IP_list1; KeyType=KT_IPv4] = ( [192.168.2.0] ),( [192.168.3.0] )
A mask can be used in the KeyDef command as shown in this example. A subnet mask [ff.ff.ff.00] is applied to IPv4SrcField. As the values in the KeyList commands are configured without any masks (an exact match), they are stored in the CAM whereas values with a mask (a wild card match) in the previous example are stored in the TCAM. Substantially greater number of values can be stored in the CAM using a subnet mask in the KeyDef command. See CAM and TCAM for more information on the CAM and the TCAM.