Key Match Examples

The key match functionality can be used in various use cases.

Monitoring subscribers over telecom core network

Specific subscribers (UE) can be monitored in a telecom core network as shown in the following figure.

The SmartNIC receives tunneled traffic between SGW and PGW in a telecom core network. The location of the PGW IP address in a frame determines whether the frame is upstream or downstream.

The following scenario is carried out.

The UE IP address is contained either in the inner source or destination IP field.
The location of PGW IP addresses in the outer layer determines whether the UE IP address is contained in the inner source or destination IP field.
- If a PGW IP address is contained in the outer source IP header, the UE IP address is contained in the inner destination IP field.
- If a PGW IP is contained in the outer destination IP header, the UE IP address is contained in the inner source IP field.
PGW IP addresses are IPv4.
UE addresses can be either IPv4 or IPv6.

// Define a protocol-filter macro for IPv4 frames containing inner IPv4.
Define IPv4_containing_IPv4 = Macro("Layer3Protocol==IPv4 AND InnerLayer3Protocol==IPv4")
// Define a filter macro for IPv4 frames containing inner IPv6.
Define IPv4_containing_IPv6 = Macro("Layer3Protocol==IPv4 AND InnerLayer3Protocol==IPv6")

// Define a macro for a IPv4 subnet of PGW.
Define PGW_IPv4 = Macro("{[ff.ff.00.00]:[201.100.0.0]}")

// Define a data-filter macro for source IP. 
Define Outer_IPv4Src = Macro("Data[ProtOffset=Layer3Header[12]; DataType=IPv4Addr]")
// Define a data-filter macro for destination IP.
Define Outer_IPv4Dst = Macro("Data[ProtOffset=Layer3Header[16]; DataType=IPv4Addr]")

// Define macros for KeySet IDs. 
Define IPv4_list = Macro("3")
Define IPv6_list = Macro("4")

KeyType[Name=KT_IPv4] = {32, 32}
KeyType[Name=KT_IPv6] = {32, 128}

KeyDef[name=IPv4Src; KeyType=KT_IPv4] = (Layer3Header[12]/32, InnerLayer3Header[16]/32)
KeyDef[name=IPv4Dst; KeyType=KT_IPv4] = (Layer3Header[16]/32, InnerLayer3Header[12]/32)

KeyDef[name=IPv6Src; KeyType=KT_IPv6] = (Layer3Header[12]/32, InnerLayer3Header[24]/128)
KeyDef[name=IPv6Dst; KeyType=KT_IPv6] = (Layer3Header[16]/32, InnerLayer3Header[8]/128)

Assign[StreamId=0; Priority=0] = Port==0 and IPv4_containing_IPv4 and Outer_IPv4Src==PGW_IPv4 \\
and Key(IPv4Dst)==IPv4_list
Assign[StreamId=0; Priority=1] = Port==0 and IPv4_containing_IPv4 and Outer_IPv4Dst==PGW_IPv4 \\
and Key(IPv4Src)==IPv4_list

Assign[StreamId=1; Priority=0] = Port==0 and IPv4_containing_IPv6 and Outer_IPv4Src==PGW_IPv4 \\
and Key(IPv6Dst)==IPv6_list
Assign[StreamId=1; Priority=1] = Port==0 and IPv4_containing_IPv6 and Outer_IPv4Dst==PGW_IPv4 \\
and Key(IPv6Src)==IPv6_list

// Pairs of PGW IP and subscriber IP.
// Subscriber IP can be IPv4 or IPv6 and have any mask and value.
KeyList[KeyType=KT_IPv4; KeySet=IPv4_list] = ([201.100.84.166], {[ff.ff.00.00]:[192.168.1.2]})
KeyList[KeyType=KT_IPv4; KeySet=IPv4_list] = ([201.100.84.166], [12.23.34.45])
KeyList[KeyType=KT_IPv4; KeySet=IPv4_list] = ([201.100.34.38], {[ff.f0.00.00]:[192.168.1.2]})
KeyList[KeyType=KT_IPv4; KeySet=IPv4_list] = ([201.100.34.38], [12.23.34.45])

KeyList[KeyType=KT_IPv6; KeySet=IPv6_list] = ([201.100.84.166], \\
{[ffff:ffff:ffff:ffff:ffff:ffff:ffff:0000]:[d7a0:4e95:0:0:0:0:af:0000]})
KeyList[KeyType=KT_IPv6; KeySet=IPv6_list] = ([201.100.84.166], [91:92:0:0:0:0:93:94])
KeyList[KeyType=KT_IPv6; KeySet=IPv6_list] = ([201.100.34.38], \\
{[ffff:ffff:ffff:ffff:ffff:ffff:ffff:0000]:[d7a0:4e95:0:0:0:0:af:0000]})
KeyList[KeyType=KT_IPv6; KeySet=IPv6_list] = ([201.100.34.38], [91:92:0:0:0:0:93:94])

In this NTPL example, two data filters (Outer_IPv4Src and Outer_IPv4Dst) are defined to detect the PGW IP address location. The key test for each frame is performed as follows:

For the frames with the inner layer IPv4:
- The key tests are performed on the outer source IPv4 address and the inner destination IPv4 address, if the outer source IPv4 address matches PGW_IPv4.
- The key tests are performed on the outer destination IPv4 address and the inner source IPv4 address, if the outer destination IPv4 address matches PGW_IPv4.
For the frames with the inner layer IPv6:
- The key tests are performed on the outer source IPv4 address and the inner destination IPv6 address, if the outer source IPv4 address matches PGW_IPv4.
- The key tests are performed on the outer destination IPv4 address and the inner source IPv6 address, if the outer destination IPv4 address matches PGW_IPv4.

Monitoring voice services over telecom core network

This example shows configuring the SmartNIC to capture traffic for the voice monitoring and analysis. The SmartNIC receives frames from interfaces over inside and outside tunnels between eNodeB and SGW network segments in a telecom core network as shown in this figure.

The SmartNIC receives frames from interfaces over inside and outside tunnels between eNodeB and SGW network segments in a telecom core network

See the NTPL example.

// Define macros for L4 source and destination port fields.
Define SrcPort = Macro("Data[ProtOffset=Layer4Header[0];DataType=ByteStr2]")
Define DstPort = Macro("Data[Protoffset=Layer4Header[2];DataType=ByteStr2]")
Define InnerSrcPort = Macro("Data[ProtOffset=InnerLayer4Header[0];DataType=ByteStr2]")
Define InnerDstPort = Macro("Data[ProtOffset=InnerLayer4Header[2];DataType=ByteStr2]")

Define Outer_IP_list = Macro("3")
Define Inner_IP_list = Macro("4")

// 2 tuple sorted IPv4 hash mode.
Define Hash2TupleIPv4 = Hash(HashWord0_3=Layer3Header[12]/32,HashWord4_7=Layer3Header[16]/32,XOR=True)
// 2 tuple sorted inner IPv4 hash mode.
Define HashInner2TupleIPv4 = Hash(HashWord0_3=InnerLayer3Header[12]/32,\\
HashWord4_7=InnerLayer3Header[16]/32,XOR=True)

// 5 tuple sorted IPv4 hash mode.
Define Hash5TupleIPv4 = Hash(HashWord0_3=Layer3Header[12]/32,HashWord4_7=Layer3Header[16]/32, \\
HashWord8=Layer4Header[0]/32,HashWordP=IpProtocol,XOR=True)

// 5 tuple sorted inner IPv4 hash mode.
Define HashInner5TupleIPv4 = Hash(HashWord0_3=InnerLayer3Header[12]/32,HashWord4_7=InnerLayer3Header[16]/32,\\
HashWord8=InnerLayer4Header[0]/32,HashWordP=InnerIpProtocol,XOR=True)

// Define key type for single IPv4 address.
KeyType[Name=KT_IPv4] = {32}

// Key definition for outer IPv4 src address.
KeyDef[Name=OuterIPv4Src;KeyType=KT_IPv4] = (Layer3Header[12]/32)

// Key definition for inner IPv4 src address.
KeyDef[Name=InnerIPv4;KeyType=KT4_IPv4] = (InnerLayer3Header[12]/32)

// Capture GTPv2-C traffic.
Assign[Priority=0;StreamId=(30..31);Hash=Hash2TupleIPv4] = TunnelType==GTPv2-C

// Capture SIP traffic (not tunneled).
Assign[Priority=1;StreamId=(27..29);Hash=Hash2TupleIPv4] = SrcPort==(5060..5070) OR SrcPort==5073,5091 \\
OR DstPort==(5060..5070) OR DstPort==5073,5091

// Capture UDP + outer ip addresses (not tunneled).
Assign[Priority=2;StreamId=(15..26);Hash=Hash5TupleIPv4] = Layer3Protocol==IPv4 AND Layer4Protocol==UDP \\
AND TunnelType==Other AND Key(OuterIPv4Src)==Outer_IP_list

// Capture SIP traffic (tunneled).
Assign[Priority=1;StreamId=(12..14);Hash=HashInner2TupleIPv4] = InnerSrcPort==(5060..5070) OR \\
InnerSrcPort==5073,5091 OR InnerDstPort==(5060..5070) OR InnerDstPort==5073,5091

// Match GTPv1 + inner IP addresses (tunneled).
Assign[Priority=3;StreamId=(0..11);Hash=HashInner5TupleIPv4] = TunnelType==GTPv1-U AND \\
InnerLayer3Protocol==IPv4 AND InnerLayer4Protocol != Other AND Key(InnerIPv4)==Inner_IP_list

// IP list for the outer layer.
KeyList[KeyType=KT4;KeySet=Outer_IP_list] = ([10.10.4.5]),([10.10.3.6])
// IP list for the inner layer.
KeyList[KeyType=KT4;KeySet=Inner_IP_list] = ([192.168.33.2]),([192.168.2.4])

The following rules are applied in this example.

Stream 30 and 31: GTPv2-C traffic which are distributed using 2 tuple sorted hash mode (source and destination IP addresses).
Stream 27 to 29: SIP traffic (not tunneled traffic) using UDP port filters (5060 to 5070, 5073 and5091). Traffic is distributed using 2 tuple sorted hash mode (source and destination IP addresses).
Stream 15 to 26: UDP traffic (not tunneled traffic) filtering a certain list of IP addresses and distribute using 5 tuple sorted hash mode.
Stream 12 to 14: SIP traffic (tunneled traffic) using UDP port filters (5060 to 5070, 5073 and 5091). Traffic is distributed using 2 tuple sorted hash mode (inner layer source and destination IP addresses).
Stream 0 to 11: UDP traffic inside GTPv1 tunnel filtering a certain list of inner layer IP addresses. Traffic is distributed using 5 tuple sorted hash mode (inner layer IP addresses and UDP port numbers).

Capturing based on MAC addresses, IP addresses or L4 ports

The following NTPL example illustrates how to configure filters for capturing frames with specified MAC addresses, IP addresses or layer 4 ports.

// MAC address filters
Define mDstMac = Macro("Data[ProtOffset=Layer2Header[0]; DataType=MacAddr]")
Define mSrcMac = Macro("Data[ProtOffset=Layer2Header[6]; DataType=MacAddr]")
Assign[StreamId=0; Priority=30] = (mDstMac == [5C:BA:EF:78:2E:17] OR mSrcMac == [5C:BA:EF:78:2E:17])

// Outer layer field definitions
Define OuterSrcIPv4 = Field(Layer3Header[12]/32)
Define OuterDstIPv4 = Field(Layer3Header[16]/32)
Define OuterSrcPort = Field(Layer4Header[0]/16)
Define OuterDstPort = Field(Layer4Header[2]/16)

// Inner layer field definitions
Define InnerSrcIPv4 = Field(InnerLayer3Header[12]/32)
Define InnerDstIPv4 = Field(InnerLayer3Header[16]/32)
Define InnerSrcPort = Field(InnerLayer4Header[0]/16)
Define InnerDstPort = Field(InnerLayer4Header[2]/16)

// Key type definition for (IPv4, Port) pair
KeyType[Name=IPv4PortKT; Access=Full] = {32, 16}

// Outer layer key defintions
KeyDef[Name=OuterLayerSrc; KeyType=IPv4PortKT] = (OuterSrcIPv4, OuterSrcPort)
KeyDef[Name=OuterLayerDst; KeyType=IPv4PortKT] = (OuterDstIPv4, OuterDstPort)

// Inner layer key defintions
KeyDef[Name=InnerLayerSrc; KeyType=IPv4PortKT] = (InnerSrcIPv4, InnerSrcPort)
KeyDef[Name=InnerLayerDst; KeyType=IPv4PortKT] = (InnerDstIPv4, InnerDstPort)

Define mAnyIPv4 = Macro("{[00.00.00.00]:[000.000.000.000]}")
Define mAnyPort = Macro("{0x0000:0x0000}")

// Port values
KeyList[KeyType=IPv4PortKT; KeySet=3] = (mAnyIPv4,443) // Single port value
KeyList[KeyType=IPv4PortKT; KeySet=3] = (mAnyIPv4,{0xFFFE:5060}) // Ports 5060 and 5061

// IPv4 values
KeyList[KeyType=IPv4PortKT; KeySet=3] = ([192.168.2.1],  mAnyPort) // Single IPv4 value
KeyList[KeyType=IPv4PortKT; KeySet=3] = ({[FF.FF.FF.00]:[192.168.3.0]},  mAnyPort) // Subnet

Assign[StreamId=0; Priority=40] = InnerLayer3Protocol==IPv4 AND InnerLayer4Protocol==UDP,TCP AND (Key(InnerLayerSrc)==3 OR Key(InnerLayerDst)==3)
Assign[StreamId=0; Priority=50] =      Layer3Protocol==IPv4 AND      Layer4Protocol==UDP,TCP AND (Key(OuterLayerSrc)==3 OR Key(OuterLayerDst)==3)

In this example, data filters are used to specify MAC addresses and key match filters are used to specify IP addresses and layer 4 ports.