12 Using the Signature Editor Introduction

12 Using the Signature Editor Introduction
CH A P T E R
12
Using the Signature Editor
Revised: December 14, 2011, OL-7205-19
Introduction
This module describes the Signature Editor tool and how to use it to create and modify Dynamic
Signature Script (DSS) files.
The Signature Editor tool allows you to create and modify DSS files that can add and modify protocols
and protocol signatures in the Cisco Service Control Application for Broadband (SCA BB), based on
your knowledge of new network protocols that are not yet supported by SCA BB.
•
The Signature Editor Console, page 12-1
•
Managing DSS Files, page 12-1
•
How to Create DSS Files, page 12-11
•
How to Edit DSS Files, page 12-14
•
How to Import DSS Files, page 12-15
The Signature Editor Console
The Signature Editor writes log and error messages to the Signature Editor Console (in the Console
view), when appropriate.
Managing DSS Files
•
Installing new signatures to an active service configuration is described in Working with Protocol
Packs, page 4-19.
•
Working with signatures in the Service Configuration Editor is described in Managing Protocol
Signatures, page 7-39.
•
Using servconf, the Server Configuration Utility, to apply signatures is described in The SCA BB
Service Configuration Utility, page 13-1.
The DSS file components, and the creation and editing of DSS files, are explained in the following
sections.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-1
Chapter 12
Using the Signature Editor
Managing DSS Files
The DSS File Components
The DSS file components are displayed in the Script pane of the Signature Editor, in a tree structure. By
selecting the appropriate node of the DSS component tree, you can define the properties associated with
the node in the Property pane.
The DSS file components are described in the following sections.
•
The DSS File, page 12-2
•
DSS Protocol List, page 12-2
•
Information About DSS Protocols, page 12-3
•
DSS Signatures, page 12-4
•
DSS Deep Inspection Clauses, page 12-9
•
DSS Deep Inspection Conditions, page 12-9
The DSS File
The DSS file name is the root node of the DSS file component tree.
When you select the root node, you can define the following properties for the DSS file:
•
Script Name—Enter a meaningful name for this script.
•
Script Description—Enter the reason for creating this script and describe its contents.
•
Script Version (Major)
•
Script Version (Minor)
•
Script Build Number (Major)
•
Script Build Number (Minor)
•
Created for Application Version—Select from a list of predefined values.
Figure 12-1 shows the default values for the DSS file properties.
Figure 12-1
Default Values for DSS File Properties
The DSS file contains a single protocol list.
DSS Protocol List
The protocol list has no properties to define. It contains all the protocols that are being added, modified,
or enhanced.
Cisco Service Control Application for Broadband User Guide
12-2
OL-7205-19
Chapter 12
Using the Signature Editor
Managing DSS Files
Information About DSS Protocols
When you select a Protocol node in the DSS file component tree, you can define the following properties
of the protocol:
•
Basic:
– Protocol Name—See Setting Protocol Name and ID, page 12-3.
– Protocol Description
– Protocol ID—See Setting Protocol Name and ID, page 12-3.
•
Protocol Category:
– Buddy Protocol—See The Buddy Protocol, page 12-4.
– Protocol Families—Assign the protocol to one or more protocol families:
– P2P
– SIP
– VOIP
– Worm
Associating a protocol with a protocol family allows reports about the family to include the new
protocol.
Figure 12-2 shows the default values for the protocol properties.
Figure 12-2
Default Values for the Protocol Properties
Protocols contain signatures.
Setting Protocol Name and ID
A DSS can include two types of protocols:
•
A protocol new to SCA BB—The protocol is being defined in the DSS.
•
A protocol that SCA BB already supports—The protocol identification is being enhanced or
modified in the DSS.
Selecting a name and ID is different for the two cases:
•
For a protocol new to SCA BB, the name must not match any of the protocol names that SCA BB
already supports. To see a list of supported-protocol names, open the Protocol Settings dialog box
in the Service Configuration Editor (see How to View Protocols, page 7-22). Assign the protocol a
unique ID in the range 5000 to 9998.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-3
Chapter 12
Using the Signature Editor
Managing DSS Files
•
For an existing protocol, the protocol name and ID in the DSS must be identical to the protocol name
and ID in the service configuration. Locate the name and ID in the Protocol Settings dialog box in
the Service Configuration Editor (see How to View Protocols, page 7-22).
The Buddy Protocol
To simplify the configuration of new protocols added by a DSS, the DSS may specify a Buddy Protocol
for a new protocol. If, when importing a DSS to a service configuration, the application encounters
service elements referring to the Buddy Protocol, it automatically duplicates the set of service elements
that use the Buddy Protocol and replaces all references to the Buddy Protocol with references to the new
protocol. The association of the new protocol to services will match that of the Buddy Protocol.
DSS Signatures
A protocol may contain as many different signatures as necessary.
Four different types of signatures may be added to a protocol:
•
String Match Signatures
•
Payload Length Signatures
•
HTTP User Agent Signatures
•
HTTP x-Header Signatures
Each of the four signature types tests different conditions against the first payload packet of the flows.
These signature types and their conditions are described in the following subsections.
String Match Signatures and Payload Length Signatures can contain deep inspection clauses. A signature
whose first payload packet conditions are met will accept a flow if the conditions of any of its deep
inspection clauses are also met.
DSS String Match Signature
When you select a String Match Signature node in the DSS file component tree, you can define the
following properties of the signature:
•
Signature Name—A unique name
•
Signature Description
•
Signature ID—A value in the range 0xC010000 to 0xC0100FF (decimal 201392128 to 201392383)
•
First Payload Packet Conditions:
– Fixed Size Byte String—(Display only) Shows the string formed by the next four fields:
– [0]—Enter the ASCII code for the first byte of the string, or enter “*” to indicate that any value
is acceptable.
– [1]—Enter the ASCII code for the second byte of the string, or enter “*” to indicate that any
value is acceptable.
– [2]—Enter the ASCII code for the third byte of the string, or enter “*” to indicate that any value
is acceptable.
– [3]—Enter the ASCII code for the fourth byte of the string, or enter “*” to indicate that any
value is acceptable.
Cisco Service Control Application for Broadband User Guide
12-4
OL-7205-19
Chapter 12
Using the Signature Editor
Managing DSS Files
– String Position—The position of the Fixed Size Byte String in the packet. The position is the
location of the first byte of the string, counting from the first byte in the packet. To match the
string with the beginning of the packet, this value should be zero. The value must be an integer
divisible by four.
– Packet Direction—The initiating side of the first packet in the flow that has a payload. This field
can have one of three values:
– From Server
– From Client
– Don’t Care (either side)
– Port Range—(Display only) The port range formed by the next two fields. The default value is
the entire port range: 0 to 65535.
– From Port—Lower bound of the port range (inclusive)
– To Port—Upper bound of the port range (inclusive)
– Check before PL—Toggles between the values true and false.
This field indicates whether to test the signature before or after the execution of the SCA BB
built-in PL (Protocol Library) classification. Testing this signature before the execution of the
built-in classification means that if the flow matches this signature, the PL classification will be
skipped. If this field is set to “false”, this signature will be tested only if the PL classification
fails to identify any of its supported protocol signatures.
– Asymmetric Routing Classification Mode—This field indicates whether to test the signature
depending on the state of the asymmetric routing classification mode. It can have one of three
values:
– Don't Care—Signifies that this signature should be tested whether asymmetric routing
classification mode is enabled or disabled.
– Disabled
– Enabled
– Flow Type—(Display only) This field shows to which flow types the condition applies (the
condition may be applied to multiple types). It is ignored unless asymmetric routing
classification mode is enabled.
The flow type is specified by the next four fields:
– Bidirectional—Toggles between the values true and false.
– Unidirectional Client Side—Toggles between the values true and false. Applies to TCP flows
for which only packets from the client side have been detected.
– Unidirectional Server Side—Toggles between the values true and false. Applies to TCP flows
for which only packets from the server side have been detected.
– Unknown (UDP)—Toggles between the values true and false. Applies to UDP flows for which
packets from only one direction have been detected.
Caution
Set Check before PL to true only if the signature identifies the protocol according to the first payload
packet only. If the signature also uses a Deep Inspection Condition that looks into later packets, and the
signature does not match the flow, the PL classification will not perform properly.
Figure 12-3 shows the default values for the String Match Signature properties.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-5
Chapter 12
Using the Signature Editor
Managing DSS Files
Figure 12-3
Default Values for the String Match Signature Properties
A flow that matches the first payload packet conditions of a String Match Signature will then be
compared against the deep inspection conditions of the signature (see DSS Deep Inspection Conditions,
page 12-9).
DSS Payload Length Signature
When you select a Payload Length Signature node in the DSS file component tree, you can define the
following properties of the signature:
•
Signature Name—A unique name
•
Signature Description
•
Signature ID—A value in the range 0xC010000 to 0xC0100FF (decimal 201392128 to 201392383)
•
First Payload Packet Conditions:
– Packet Direction—The initiating side of the first packet in the flow that has a payload. This field
can have one of three values:
– From Server
– From Client
– Don’t Care (either side)
– Payload Length—The number of bytes in the payload packet.
– Port Range—(Display only) The port range formed by the next two fields. The default value is
the entire port range: 0 to 65535.
– From Port—Lower bound of the port range (inclusive)
– To Port—Upper bound of the port range (inclusive)
– Check before PL—Toggles between the values true and false.
Cisco Service Control Application for Broadband User Guide
12-6
OL-7205-19
Chapter 12
Using the Signature Editor
Managing DSS Files
This field indicates whether to test the signature before or after the execution of the SCA BB
built-in PL (Protocol Library) classification. Testing this signature before the execution of the
built-in classification means that if the flow matches this signature, the PL classification will be
skipped. If this field is set to “false”, this signature will be tested only if the PL classification
fails to identify any of its supported protocol signatures.
– Asymmetric Routing Classification Mode—This field indicates whether to test the signature
depending on the state of the asymmetric routing classification mode. It can have one of three
values:
– Don't Care—Signifies that this signature should be tested whether asymmetric routing
classification mode is enabled or disabled.
– Disabled
– Enabled
– Flow Type—(Display only) This field shows to which flow types the condition applies (the
condition may be applied to multiple types). It is ignored unless asymmetric routing
classification mode is enabled.
The flow type is specified by the next four fields:
– Bidirectional—Toggles between the values true and false.
– Unidirectional Client Side—Toggles between the values true and false. Applies to TCP flows
for which only packets from the client side have been detected.
– Unidirectional Server Side—Toggles between the values true and false. Applies to TCP flows
for which only packets from the server side have been detected.
– Unknown (UDP)—Toggles between the values true and false. Applies to UDP flows for which
packets from only one direction have been detected.
Caution
Set Check before PL to true only if the signature identifies the protocol according to the first payload
packet only. If the signature also uses a Deep Inspection Condition that looks into later packets, and the
signature does not match the flow, the PL classification will not perform properly.
Figure 12-4 shows the default values for the Payload Length Signature properties.
Figure 12-4
Default Values for the Payload Length Signature Properties
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-7
Chapter 12
Using the Signature Editor
Managing DSS Files
A flow that matches the first payload packet conditions of a Payload Length Signature will then be
compared against the deep inspection conditions of the signature (see DSS Deep Inspection Conditions,
page 12-9).
DSS HTTP User Agent Signature
When you select an HTTP User Agent Signature node in the DSS file component tree, you can define
the following properties of the signature:
•
Signature Name—A unique name
•
Signature Description
•
Signature ID—A value in the range 0xC010000 to 0xC0100FF (decimal 201392128 to 201392383)
•
Conditions:
– User Agent—The value of the User Agent field in the HTTP header
Figure 12-5 shows the default values for the HTTP User Agent signature properties.
Figure 12-5
Default Values for the HTTP User Agent Signature Properties
DSS HTTP x-Header Signature
When you select an HTTP x-Header Signature node in the DSS file component tree, you can define the
following properties of the signature:
•
Signature Name—A unique name
•
Signature Description
•
Signature ID—A value in the range 0xC010000 to 0xC0100FF (decimal 201392128 to 201392383)
•
Conditions:
– x-Header Field Name—A name of a field in the x-Header of the HTTP header
Figure 12-6 shows the default values for the DSS file properties.
Figure 12-6
Default Values for the DSS File Properties
Cisco Service Control Application for Broadband User Guide
12-8
OL-7205-19
Chapter 12
Using the Signature Editor
Managing DSS Files
DSS Deep Inspection Clauses
A deep inspection clause is a conjunctive clause of deep inspection conditions—a signature will accept
a flow only if all conditions in a clause are met.
Note
If a signature has multiple deep inspection clauses, the clauses (and the deep inspection conditions
making up each clause) are tested in an order based on the value of the Packet Number property of the
deep inspection conditions.
After the first payload packet is accepted by the first payload packet conditions, the clause containing
the condition with the lowest Packet Number is tested. The other conditions in this clause are checked
in ascending Packet Number order. Thus, the Packet Number of any condition in a clause cannot be less
than the largest Packet Number in the clause it succeeds.
DSS Deep Inspection Conditions
A deep inspection condition is a set of conditions that are checked against flows that pass the first
payload packet conditions screening of String Match Signatures or Payload Length Signatures.
When you select a Deep Inspection Condition node in the DSS file component tree, you can define the
following properties of the deep inspection condition:
•
Packet Direction—The initiating side of the first packet in the flow that has a payload. This field can
have one of three values:
– From Server
– From Client
– Don’t Care (either side)
•
Packet Number—The number of the packet in the flow. The payload packets are numbered from
zero; packets are counted in both directions.
•
Payload Length—The length of the packet in bytes. Enter zero to indicate that any value is
acceptable.
•
Printable Characters—Test if the inspected packet contains only printable characters. This field can
have one of three values:
– Printable Characters Only
– At Least One Non-Printable
– Don’t Care
•
Substring Search—Match a search string with a specific location in the packet. Leave the Search
String fields empty if this condition is irrelevant.
– Position Offset—The position from which to start searching for the search string in the packet.
The offset is relative to the location specified in the Start Search From field.
– Start Search From—This field can have one of two values:
– Packet beginning
– Last match
Last match means that the search for this search string starts where the last search match ended.
The last match may be from a previous substring search or from the last string-based first
payload packet condition.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-9
Chapter 12
Using the Signature Editor
Managing DSS Files
– Searchable Range—Search in this number of bytes for the search string.
– Search Packets—This field can have one of two values:
– This packet only
– Multiple packets
Multiple Packets means that the search may span across packets, as long as the overall number
of bytes is less than the number specified in the Searchable Range field.
– Search String—Enter the search string in one of the following three fields (the other two fields
will be updated automatically):
– ASCII Codes—Enter the ASCII codes for the characters of the search string. Separate each code
by a comma.
– Byte String—Enter the actual search string.
– Hex Values—Enter the hexadecimal values of the ASCII codes for the characters of the search
string. Separate each code by a comma.
•
Transport Protocol—This field can have one of three values:
– TCP
– UDP
– Don’t Care (either TCP or UDP)
Figure 12-7 shows the default values for the deep inspection condition properties.
Figure 12-7
Default Values for the Deep Inspection Condition Properties
The structure of deep inspection conditions is the same for String Match Signatures and Payload Length
Signatures.
Cisco Service Control Application for Broadband User Guide
12-10
OL-7205-19
Chapter 12
Using the Signature Editor
How to Create DSS Files
How to Create DSS Files
If you have a DSS file open in the Signature Editor, save it before you create a new DSS file. All unsaved
changes will be lost.
Step 1
From the toolbar, click
(Create a New DSS File).
A DSS component tree containing a DSS File node, a Protocol List node, and a Protocol node, is
displayed in the Script view.
The default properties of the new DSS file are displayed in the Properties view (Figure 12-8).
Figure 12-8
Step 2
Properties Tab
Edit the DSS file properties.
For an explanation of the properties, see The DSS File, page 12-2.
Step 3
Click the Protocol node.
The protocol properties appear in the Properties view (Figure 12-9).
Step 4
Edit the protocol properties.
For an explanation of the properties, see Information About DSS Protocols, page 12-3.
Step 5
Click the drop-down arrow next to the
button.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-11
Chapter 12
Using the Signature Editor
How to Create DSS Files
Figure 12-9
Step 6
Protocol Properties
From the drop-down menu that appears, select a signature type.
A Signature node is added under the Protocol node.
If you selected a String Match Signature or a Payload Length Signature, a Deep Inspection Clause node
and a Deep Inspection Condition node are also added (Figure 12-10).
Figure 12-10
Step 7
Protocol List Information
Click the Signature node.
The signature properties appear in the Properties view.
Step 8
Edit the signature properties.
For an explanation of the properties., see DSS Signatures, page 12-4
Step 9
If you selected a String Match Signature or a Payload Length Signature, click the Deep Inspection
Condition node to edit the deep inspection condition properties.
The deep inspection condition properties appear in the Properties view.
For an explanation of the properties, see DSS Deep Inspection Conditions, page 12-9.
Step 10
Add additional deep inspection conditions, deep inspection clauses, signatures, and protocols as needed.
Step 11
From the toolbar, click
•
(Save).
If there are duplicate protocol names or protocol IDs, a Validation Error message appears
(Figure 12-11).
Cisco Service Control Application for Broadband User Guide
12-12
OL-7205-19
Chapter 12
Using the Signature Editor
How to Create DSS Files
Figure 12-11
Validation Error
Click OK, remove the duplication, and then click
(Save) again.
A Save As dialog box appears.
Step 12
Browse to the folder where you want to save the new DSS file.
Step 13
In the File name field, enter an appropriate name for the DSS file.
Step 14
Click Save.
The Save As dialog box closes.
The DSS file is saved.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-13
Chapter 12
Using the Signature Editor
How to Edit DSS Files
How to Edit DSS Files
You can edit an existing DSS file, and add new protocols, or modify or delete existing protocols.
Caution
Step 1
If you have a DSS file open in the Signature Editor, save it before you open a different DSS file. All
unsaved changes will be lost.
From the toolbar, click
(Open a DSS File).
An Open dialog box appears.
Step 2
Browse to the DSS file that you want to edit.
Step 3
Click Open.
The Open dialog box closes.
The DSS Component tree of the selected file is displayed in the Script view.
The DSS File node is selected, and the properties of the DSS file are displayed in the Properties view.
Step 4
Add, edit, or delete DSS file components.
See the subsections of The DSS File Components, page 12-2for an explanation of the properties of the
different components.
Step 5
Save the modified DSS file.
•
To overwrite the current DSS file with the changes you have made:
– From the toolbar, click
(Save).
The changes to the DSS file are saved.
•
To save the modified DSS file with a new name:
1.
Choose File > Save As.
A Save As dialog box appears.
2.
Browse to the folder where you want to save the new DSS file.
3.
In the File name field, enter an appropriate name for the DSS file.
4.
Click Save.
The Save As dialog box closes.
The modified DSS file is saved with the new name.
Cisco Service Control Application for Broadband User Guide
12-14
OL-7205-19
Chapter 12
Using the Signature Editor
How to Import DSS Files
How to Import DSS Files
You can import DSS files into the file you are currently editing.
Note
Step 1
Importing signatures may create duplication of protocol names or protocol IDs.
From the Console main menu, choose File > Import.
The Import dialog box appears (Figure 12-12).
Figure 12-12
Import
Step 2
From the import source list, select Import protocols from one DSS file to another DSS.
Step 3
Click Next.
The second screen of the Import dialog box opens (Figure 12-13).
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-15
Chapter 12
Using the Signature Editor
How to Import DSS Files
Figure 12-13
Step 4
Import Protocols from One DSS File to Another
Click Choose File.
An Open dialog box appears.
Step 5
Browse to the DSS file to import.
Step 6
Click Open.
The Open dialog box closes.
Information about the DSS file that you have chosen is displayed in the DSS File Information area
(Figure 12-14).
Cisco Service Control Application for Broadband User Guide
12-16
OL-7205-19
Chapter 12
Using the Signature Editor
How to Import DSS Files
Figure 12-14
Step 7
Import Protocols from One DSS File to Another
Click Finish.
The Import dialog box closes.
The content of the selected DSS file is imported into the Signature Editor.
Cisco Service Control Application for Broadband User Guide
OL-7205-19
12-17
Chapter 12
Using the Signature Editor
How to Import DSS Files
Cisco Service Control Application for Broadband User Guide
12-18
OL-7205-19
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertising