Security Configuration Guide: Flexible Packet Matching Cisco IOS Release 15.1M&T

Flexible Packet Matching XML Configuration

The Flexible Packet Matching XML Configuration feature allows the use of eXtensible Markup Language (XML) to define traffic classes and actions (policies) to assist in blocking network attacks. The XML file used by Flexible Packet Matching (FPM) is called the traffic classification definition file (TCDF). The TCDF gives you an alternative to the command-line interface (CLI) as a method to define traffic classification behavior. Traffic classification behavior is identical regardless of the method you use.

Finding Feature Information

Your software release may not support all the features documented in this module. For the latest feature information and caveats, see the release notes for your platform and software release. To find information about the features documented in this module, and to see a list of the releases in which each feature is supported, see the "Feature Information for Flexible Packet Matching XML Configuration" section.

Use Cisco Feature Navigator to find information about platform support and Cisco software image support. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.

Contents

•Prerequisites for the Flexible Packet Matching XML Configuration

•Restrictions for the Flexible Packet Matching XML Configuration

•Information About the Flexible Packet Matching XML Configuration

•How to Create and Load Traffic Classification Definition Files for the FPM XML Configuration

•Configuration Examples for Creating and Loading Traffic Classification Definition Files for the FPM XML Configuration

•Additional References

•Feature Information for Flexible Packet Matching XML Configuration

•Glossary

Prerequisites for the Flexible Packet Matching XML Configuration

The Flexible Packet Matching XML Configuration feature has the following prerequisites:

•A protocol header definition file (PHDF) relevant to the TCDF must be loaded on the router.

•Although access to an XML editor is not required, using one might make the creation of the TCDF easier.

•You must be familiar with XML file syntax.

Restrictions for the Flexible Packet Matching XML Configuration

The Flexible Packet Matching XML Configuration has the following restrictions:

•The FPM TCDF cannot be used to mitigate an attack that requires stateful classification.

•Because FPM is stateless, it cannot keep track of port numbers being used by protocols that dynamically negotiate ports. Thus, when using the FPM TCDF, port numbers must be explicitly specified.

•FPM cannot perform IP fragmentation or TCP flow reassembly.

Information About the Flexible Packet Matching XML Configuration

Before you create and load the TCDF XML configuration files for use with FPM, you should understand the following concepts.

•Traffic Classification Definition Files for the Flexible Packet Matching XML Configuration

•Protocol Header Definition Files for Traffic Classification Definitions

•Traffic Classification Description File Format and Use

•Traffic Class Definitions for a Traffic Classification Definition File

•Policy Definitions for a Traffic Classification Definition File

Traffic Classification Definition Files for the Flexible Packet Matching XML Configuration

FPM uses a TCDF to define policies that can block attacks on the network. FPM is a packet classification feature that allows users to define one or more classes of network traffic by pairing a rich set of standard matching operators with user-defined protocol header fields. FPM users can create their own stateless packet classification criteria and define policies with multiple actions (such as drop, log, or send Internet Control Message Protocol [ICMP] unreachable) to immediately block new viruses, worms, and attacks on the network.

Before the release of the Flexible Packet Matching XML Configuration feature, FPM defined traffic classes (class maps), policies (policy maps), and service policies (attach policy maps to a class maps) through the use of CLI commands. With TCDFs, FPM can use XML as an alternative to the CLI to define classes of traffic and specify actions to apply to the traffic classes. Traffic classification behavior is the same whether you create the behavior using a TCDF or configure it using CLI commands. Once a TCDF is created, it can be loaded on any FPM-enabled device in the network.

For more information on FPM, see the Flexible Packet Matching feature module.

Protocol Header Definition Files for Traffic Classification Definitions

TCDFs require that a relevant PHDF is already loaded on the device. A PHDF defines each field contained in the header of a particular protocol. Each field is described with a name, optional comment, an offset (the location of the protocol header field in relation to the start of the protocol header), and the length of the field. The total length is specified at the end of each PHDF.

The description of a traffic class in a TCDF file can contain header fields defined in a PHDF. If the PHDF is loaded on the router, the class specification to match begins with a list of the protocol headers in the packet. In the TCDF, the traffic class is associated with a policy that binds the match to an action, such as drop, log, or send ICMP unreachable.

FPM provides ready-made definitions for these standard protocols, which can be loaded onto the router with the load protocol command: ether.phdf, ip.phdf, tcp.phdf, and udp.phdf. You can also write your own custom PHDFs using XML if one is required for the TCDF.

Note Because PHDFs are defined via XML, they are not shown in a running configuration.

For more information about PHDFs, see the Flexible Packet Matching feature module.

Traffic Classification Description File Format and Use

In the TCDF, you can define one or more classes of traffic and policies that describe specified actions for each class of traffic. The TCDF is an XML file that you create in a text file or with an XML editor. The file that you create must have a filename that has the .tcdf extension.

The TCDF has the following basic format. XML tags are shown in bold text for example purposes only.

<tdcf>

       <class ...> ... </class>

         ...

       <policy> ... </policy>

         ...

</tdcf>

For a traffic class, you can identify a match for any field or fields against any part of the packet.

Note FPM is stateless and cannot be used to mitigate an attack that requires stateful classification, that is classify across IP fragments, across packets in a TCP stream, or peer-to-peer protocol elements.

Policies can be anything from access control, quality of service (QoS), or even routing decisions. For FPM, the associated actions (policies) might include permit, drop, log, or send ICMP unreachable.

Once loaded, the TCDF-defined classes and policies can be applied to any interface or subinterface and behave in an identical manner as the CLI-defined classes and policies. You can define policies in the TCDF and apply then to any entry point to the network to block new attacks.

Traffic Class Definitions for a Traffic Classification Definition File

A class can be any traffic stream of interest. You define a traffic stream of interest by matching a particular interface or port, a source address or destination IP address, a protocol or an application. The following sections contain information you should understand before you define the traffic class in the TCDF for FPM configuration:

•Class Element Attributes for a Traffic Classification Definition File

•Match Element for a Traffic Classification Definition File

•Operator Element Attributes for a Traffic Classification Definition File

Class Element Attributes for a Traffic Classification Definition File

Table 1 lists and describes the attributes that you can associate with the class element in a TCDF for the FPM XML configuration. The class element contains attributes you can use to specify the traffic class name, its description and type, where to look in the packet, what kind of match, and when the actions should apply to the traffic.

For example, XML syntax for a stack class describing an IP, User Datagram Protocol (UDP), Simple Management Protocol (SNMP) stack might look like this:

<class name="snmp-stack" type="stack">

    <match>

       <eq field="ip.protocol" value="x"></eq>

       <eq field="udp.dport" value="161"></eq>

    </match>

</class>

Match Element for a Traffic Classification Definition File

The match element in the TCDF for FPM XML configuration contains operator elements. Operator elements are the following: eq (equal to), neq (not equal to), lt (less than), gt (greater than), range (a value in a specific range, for example, range 1 - 25), and regex (regular expression string with a maximum length of 32 characters).

In following sections, these various operators are collectively called the operator element.

Operator Element Attributes for a Traffic Classification Definition File

Table 2 lists and describes direct matching attributes that you can associate with the operator element in a TCDF for the FPM XML configuration.

Policy Definitions for a Traffic Classification Definition File

A policy is any action that you apply to a class. You should understand the following information before defining the policy in a TCDF for the FPM XML configuration:

•Policy Element Attributes for a Traffic Classification Definition File

•Action Element for a Traffic Classification Definition File

Policy Element Attributes for a Traffic Classification Definition File

Policies can be anything from access control, QoS, or even routing decisions. For FPM, the associated actions or policies might include drop, log, or send ICMP unreachable. Policies describe the action to take to mitigate attacks on the network.

Table 3 lists and describes the attributes that you can use with the policy element in the TDCF for FPM XML configuration.

The policy name in this example is sql-slammer, and the action defined for the policy is to drop the packet. This action is to be applied to the class that has the same name as the policy (class name= "sql-slammer").

<policy name="sql-slammer">

    <class name="sql-slammer"></class>

    <action>drop</action>

</policy>

Action Element for a Traffic Classification Definition File

The action element is used to specify actions to associate with a policy. The policy with the action element is applied to a defined class. The action element can contain any of the following: permit, drop, Log, SendBackIcmp, set, RateLimit, alarm, ResetTcpConnection, and DropFlow. For example:

<action>

   log

</action>

How to Create and Load Traffic Classification Definition Files for the FPM XML Configuration

Perform the following tasks to create and load TCDFs for the FPM XML configuration. You can define traffic classes and policies with multiple actions (such as drop, log, or send Internet Control Message Protocol [ICMP] unreachable) in a TCDF to assist in the blocking of new viruses, worms, and attacks on the network.

•Creating a Traffic Classification Definition File for the FPM XML Configuration (required)

•Loading a Traffic Classification Definition File for the FPM XML Configuration (required)

•Associating a Traffic Classification Definition File with an Interface or Subinterface (required)

•Displaying TCDF-Defined Traffic Classes and Policies (optional)

Creating a Traffic Classification Definition File for the FPM XML Configuration

Perform the following task to create a TCDF for FPM XML configuration. The TCDF is used to define traffic classes and the associated policies with specified actions for the purpose of blocking new viruses, worms, and attacks on the network.

The TCDF is configured in a text or XML editor. The syntax of the TCDF must comply with the XML Version 1.0 syntax and the TCDF schema. For information about Version 1.0 XML syntax, see the document at the following url:

http://www.w3.org/TR/REC-xml/

Traffic Classification Definition File Syntax Guidelines

The following list describes required and optional syntax for the TCDF:

•The TCDF filename must end in the .tcdf extension, for example, sql_slammer.tcdf.

•The TCDF contains descriptions for one or more traffic classes and one or more policy actions.

•The file is encoded in the XML notation.

•The TCDF file should begin with the following version encoding:

<?xml version="1.0" encoding="UTF-8"?>

SUMMARY STEPS

1. Open a text file or an XML editor and begin the file with the XML version and encoding declaration.

2. Identify the file as a TCDF.

3. Define the traffic class of interest.

4. Identify matching criteria for the defined class of traffic.

5. Define the action to apply to the defined class.

6. End the traffic classification definition.

7. Save the TCDF file with a filename that has a .tcdf extension.

DETAILED STEPS

Step 1 Open a text file or an XML editor and begin the file with the XML version and encoding declaration.

<?xml version="1.0" encoding="UTF-8"?> 

Step 2 Identify the file as a TCDF. For example:

<tcdf>

Step 3 Define the traffic class of interest.

For example, a stack class describing an IP and UDP stack might be described as follows. In this example, the name of the traffic class is "ip-udp," and the class type is "stack."

<class name="ip-udp" type="stack"></class>

In the following example, the name of the traffic class is slammer, the class type is access control, and the match criteria is all:

<class name="slammer" type="access-control" match="all"></class>

Step 4 Identify matching criteria for the defined classes of traffic. For example:

    <class name="ip-udp" type="stack">

       <match> 

          <eq field="ip.protocol" value="0x11" next="udp"></eq>

       </match>

    </class> 

    <class name="slammer" type="access-control" match="all">

       <match> 

          <eq field="udp.dest-port" value="0x59A"></eq>

          <eq field="ip.length" value="0x194"></eq>

          <eq start="l3-start" offset="224" size="4" value="0x00401010"></eq>

       </match>

    </class>

The traffic of interest in this TCDF matches fields defined in the PHDF files, ip.phdf and udp.phdf. The matching criteria for slammer packets is a UDP destination port number 1434 (0x59A), an IP length not to exceed 404 (0x194) bytes, and a Layer 3 position with a pattern 0x00401010 at 224 bytes from start (offset) of the IP header.

Step 5 Define the action to apply to the defined class. For example:

<policy name="fpm-udp-policy">

    <class name="slammer"></class>

    <action>Drop</action>

</policy>

The policy name in this example is fpm-udp-policy, and the action defined for the policy is to drop the packet. This action is to be applied to the class that has the name slammer.

Step 6 End the traffic classification definition. For example:

</tcdf>

Step 7 Save the TCDF file with a filename that has a .tcdf extension, for example: slammer.tcdf.

Loading a Traffic Classification Definition File for the FPM XML Configuration

Perform this task to load a TCDF for the FPM XML configuration. After the TCDF is successfully loaded, you can use service-policy CLI to attach TCDF policies to a specific interface or interfaces (see the "Associating a Traffic Classification Definition File with an Interface or Subinterface" section).

SUMMARY STEPS

1. enable

2. show protocol phdf protocol-name

3. configure terminal

4. load protocol location:filename

5. load classification location:filename

6. end

7. show class-map [type {stack | access-control}] [class-map-name]

DETAILED STEPS

Examples

The following is sample output from a show class-map command that displays the traffic classes defined in the TCDF after it is loaded on the router:

Router# show class-map

.

.

.

class-map type stack match-all ip-udp

   match field IP protocol eq 0x11 next UDP

class-map type access-control match-all slammer 

   match field UDP dest-port eq 0x59A 

   match field IP length eq 0x194 

   match start l3-start offset 224 size 4 eq 0x4011010 

.

.

.

What to Do Next

After you have defined the TCDF, you must apply that policy to an interface as shown in the following task "Associating a Traffic Classification Definition File with an Interface or Subinterface."

Associating a Traffic Classification Definition File with an Interface or Subinterface

Perform the following task to associate a TCDF with an interface or subinterface.

After the TCDF is loaded, traffic classification behavior defined using the TCDF is identical to the same behavior defined using the CLI.

Prerequisites

The TCDP and FPM must be configured on the device.

SUMMARY STEPS

1. enable

2. configure terminal

3. interface type slot/port

4. service-policy [type access-control] {input | output} policy-map-name

5. end

6. show policy-map interface [type access-control] interface-name slot/port [input | output]

DETAILED STEPS

Displaying TCDF-Defined Traffic Classes and Policies

Perform this task to display TCDF-defined traffic classes and policies.

SUMMARY STEPS

1. enable

2. show class-map [type {stack | access-control}] [class-map-name]

3. show class-map type stack [class-map-name]

4. show class-map type access-control [class-map-name]

5. show policy-map [policy-map]

6. exit

DETAILED STEPS

Step 1 enable

Use this command to enable privileged EXEC mode. Enter your password if prompted. For example:

Router> enable

Router# 

Step 2 show class-map [type {stack | access-control}] [class-map-name]

Use this command to verify that a class defined in the TCDF file is available on the device. For example:

Router# show class-map 

.

.

.

class-map type stack match-all ip-udp

   match field IP protocol eq 0x11 next UDP

class-map type access-control match-all slammer 

   match field UDP dest-port eq 0x59A 

   match field IP length eq 0x194 

   match start l3-start offset 224 size 4 eq 0x4011010 

.

.

.

Step 3 show class-map type stack [class-map name]

Use this command to display the stack type defined for the class of traffic in the TCDF file. For example:

Router# show class-map type stack ip-udp

class-map type stack match-all ip-udp

   match field IP protocol eq 0x11 next UDP

Step 4 show class-map type access-control [class-map-name]

Use this command to display the access type defined for the class in the TCDF file. For example:

Router# show class-map type access-control slammer

class-map type access-control match-all slammer 

   match field UDP dest-port eq 0x59A 

   match field IP length eq 0x194 

   match start l3-start offset 224 size 4 eq 0x4011010

Step 5 show policy-map [policy-map]

Use this command to display the contents of a policy map defined in the TCDF. For example:

Router# show policy-map fpm-udp-policy

policy-map type access-control fpm-udp-policy 

  class slammer 

    drop 

Step 6 exit

Use this command to exit to user EXEC mode. For example:

Router# exit

Router>

Configuration Examples for Creating and Loading Traffic Classification Definition Files for the FPM XML Configuration

This section contains the following configuration examples:

•Creating and Loading a Traffic Classification Definition File for Slammer Packets for the FPM XML Configuration: Example

•Creating and Loading a Traffic Classification Definition File for MyDoom Packets for the FPM XML Configuration: Example

Note The TCDF files are created in a text file or with an XML editor. In the following examples, XML tags are shown in bold text and field names in italic text. The values for the attributes are entered in quotation marks ("value").

Creating and Loading a Traffic Classification Definition File for Slammer Packets for the FPM XML Configuration: Example

The following example shows how to create and load a TCDF for slammer packets (UDP 1434) for the FPM configuration. The match criteria defined within the class element is for slammer packets with an IP length not to exceed 404 (0x194) bytes, UDP destination port 1434 (0x59A), and pattern 0x00401010 at 224 bytes from start of IP header. This example also shows how to define the policy "sql-slammer" with the action to drop slammer packets.

<?xml version="1.0" encoding="UTF-8"?>

<tcdf>

    <class name="ip-udp" type="stack">

       <match> 

          <eq field="ip.protocol" value="0x11" next="udp"></eq>

       </match>

    </class> 

    <class name="slammer" type="access-control" match="all">

       <match> 

          <eq field="udp.dest-port" value="0x59A"></eq>

          <eq field="ip.length" value="0x194"></eq>

          <eq start="l3-start" offset="224" size="4" value="0x00401010"></eq>

       </match>

    </class>

    <policy type="access-control" name="fpm-udp-policy">

       <class name="slammer"></class>

       <action>Drop</action>

    </policy>

</tcdf>

The following example shows how to load the TCDF file onto the device and apply the policy defined in the file to the interface Gigabit Ethernet 0/1:

configure terminal

load classification localdisk1:sql-slammer.tcdf

policy-map type access-control my-policy-1

class ip-udp

service-policy fpm-udp-policy

interface gigabitEthernet 0/1

 service-policy type access-control input my-policy-1

 end

Creating and Loading a Traffic Classification Definition File for MyDoom Packets for the FPM XML Configuration: Example

The following example shows how to create and load a TCDF for MyDoom packets in a text file or XML editor for the FPM XML configuration. The match criteria for the MyDoom packets are as follows:

•90 > IP length > 44

•pattern 0x47455420 at 40 bytes from start of IP header

or

•IP length > 44

•pattern 0x47455420 at 40 bytes from start of IP header

<tcdf>

    <class name="md-stack" type="stack">

        <match>

            <eq field="ip.protocol" value="6" next="tcp"></eq>

        </match> 

    </class>

    <class type="access-control" name="mydoom1">

        <match>

            <gt field="ip.length" value="44"/>

            <lt field="ip.length" value="90"/>

            <eq start="ip.version" offset="tcp.headerlength*4+20" size="4"  

                value="0x47455420"/>

        </match>

    </class>

    <class type="access-control" name="mydoom2">

        <match>

            <gt field="ip.length" value="44"/>

            <eq start="ip.version" offset="tcp.headerlength*4+58" size="4" 

                value="0x6d3a3830"/>

            <eq start="ip.version" offset="tcp.headerlength*4+20" size="4" 

                 value="0x47455420"/>

        </match>

    </class>

    <policy name="fpm-md-stack-policy">

       <class name="mydoom1"></class>

       <action>drop</action>

    </policy>

    <policy name="fpm-md-stack-policy">

       <class name="mydoom2"></class>

       <action>drop</action>

    </policy>

</tcdf>

The following example shows how to load the TCDF file onto the device and apply the policy defined in the file to the interface Ethernet 0/1:

configure terminal

load classification localdisk1:sql-slammer.tcdf

policy-map type access-control my-policy-2

class md-stack

service-policy fpm-md-stack-policy

interface Ethernet 0/1

 service-policy type access-control input my-policy-2

 end

Additional References

Related Documents

MIBs

Technical Assistance

Feature Information for Flexible Packet Matching XML Configuration

Table 4 lists the release history for this feature.

Use Cisco Feature Navigator to find information about platform support and software image support. Cisco Feature Navigator enables you to determine which software images support a specific software release, feature set, or platform. To access Cisco Feature Navigator, go to http://www.cisco.com/go/cfn. An account on Cisco.com is not required.

Note Table 4 lists only the software release that introduced support for a given feature in a given software release train. Unless noted otherwise, subsequent releases of that software release train also support that feature.

Glossary

FPM—Flexible Packet Matching. Packet classification feature that allows users to define one or more classes of network traffic by pairing a rich set of standard matching operators with user-defined protocol header fields.

packet—Logical grouping of information that includes a header containing control information and (usually) user data. Packets most often are used to refer to network layer units of data. The terms datagram, frame, message, and segment also are used to describe logical information groupings at various layers of the OSI reference model and in various technology circles.

stateful classification—Classification that requires state maintenance to identify classes of packets, for example, classifying across IP fragments, classifying across packets in a TCP stream, or classifying peer-to-peer protocols.

stateless classification—Classification that supports a match on any field or fields anywhere in Layer 2 to Layer 7 within the packet. Stateless classification can identify a packet as belonging to a class while utilizing no information other than what is in the packet itself and the class specification.

TCDF—traffic classification definition file. Extensible Markup Language (XML) file created for the purpose of defining traffic classes and policies for Flexible Packet Matching (FPM) that can assist in the blocking of attacks on the network.

XML—eXtensible Markup Language. Standard maintained by the World Wide Web Consortium (W3C). It defines a syntax that lets you create markup languages to specify information structures, which define the type of information, for example, subscriber name or address, not how the information looks (bold, italic, and so on). External processes can manipulate these information structures and publish them in a variety of formats. Text markup language designed to enable the use of SGML on the World Wide Web. XML allows you to define your own customized markup language.

Cisco and the Cisco Logo are trademarks of Cisco Systems, Inc. and/or its affiliates in the U.S. and other countries. A listing of Cisco's trademarks can be found at www.cisco.com/go/trademarks. Third party trademarks mentioned are the property of their respective owners. The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1005R)

Any Internet Protocol (IP) addresses and phone numbers used in this document are not intended to be actual addresses and phone numbers. Any examples, command display output, network topology diagrams, and other figures included in the document are shown for illustrative purposes only. Any use of actual IP addresses or phone numbers in illustrative content is unintentional and coincidental.

© 2007-2011 Cisco Systems, Inc. All rights reserved.