Table Of Contents
Using the Signature Editor
Information About Managing DSS Files
Information About DSS File Components
The Signature Editor Console
Creating DSS Files
Editing DSS Files
Importing Signatures
Using the Signature Editor
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.
•
Information About Managing DSS Files
• The Signature Editor Console
• Creating DSS Files
• Editing DSS Files
• Importing Signatures
Information About Managing DSS Files
•Installing new signatures to an active service configuration is described in How to Install Protocol Packs.
•Working with signatures in the Service Configuration Editor is described in Managing Protocol Signature.
•Using servconf, the Server Configuration Utility, to apply signatures is described in Information About The SCA BB Service Configuration Utility.
The DSS file components, and the creation and editing of DSS files, are explained in the following sections.
• Information About DSS File Components
Information About 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
• DSS Protocol List
• Information About DSS Protocols
• Information About DSS Signatures
• DSS Deep Inspection Clauses
• DSS Deep Inspection Conditions
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.
The following screen capture shows the default values for the DSS file properties.
Figure 12-1
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.
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.
–Protocol Description
–Protocol ID—See Setting Protocol Name and ID.
•Protocol Category:
–Buddy Protocol—See The Buddy Protocol.
–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.
The following screen capture shows the default values for the protocol properties.
Figure 12-2
Protocols contain signatures.
• Setting Protocol Name and ID
• The Buddy Protocol
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 ). Assign the protocol a unique ID in the range 5000 to 9998.
•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 ).
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.
Information About 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.
–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.
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.
The following screen capture shows the default values for the String Match Signature properties.
Figure 12-3
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 ).
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.
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.
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.
The following screen capture shows the default values for the Payload Length Signature properties.
Figure 12-4
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 ).
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
The following screen capture shows the default values for the HTTP User Agent signature properties.
Figure 12-5
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
The following screen capture shows the default values for the DSS file properties.
Figure 12-6
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 or 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, or 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.
–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)
The following screen capture shows the default values for the deep inspection condition properties.
Figure 12-7
The structure of deep inspection conditions is the same for String Match Signatures and Payload Length Signatures.
The Signature Editor Console
The Signature Editor writes log and error messages to the Signature Editor Console (in the Console view), when appropriate.
Creating 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
Step 2 Edit the DSS file properties.
See The DSS File for an explanation of the properties.
Step 3 Click the Protocol node.
The protocol properties appear in the Properties view.
Step 4 Edit the protocol properties.
See Information About DSS Protocols for an explanation of the properties.
Step 5 Click the drop-down arrow next to the 
button.
Figure 12-9
Step 6 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
Step 7 Click the Signature node.
The signature properties appear in the Properties view.
Step 8 Edit the signature properties.
See Information About DSS Signatures for an explanation of the properties.
Step 9 If you selected a String Match Signature or a Payload Length Signature:
a. Click the Deep Inspection Condition node.
The deep inspection condition properties appear in the Properties view.
b. Edit the deep inspection condition properties.
See DSS Deep Inspection Conditions for an explanation of the properties.
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
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.
Editing DSS Files
You can edit an existing DSS file, and add new protocols, or modify or delete existing protocols.
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.
Step 1 SFrom 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 Information About DSS File Components for 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:
–Choose File >Save As.
A Save As dialog box appears.
–Browse to the folder where you want to save the new DSS file.
–In the File name field, enter an appropriate name for the DSS file.
–Click Save.
The Save As dialog box closes.
The modified DSS file is saved with the new name.
Importing Signatures
You can import DSS files into the file you are currently editing.
Note Importing signatures may create duplication of protocol names or protocol IDs.
Step 1 From the Console main menu, choose File >Import.
The Import dialog box appears.
Figure 12-12
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
Step 4 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
Step 7 Click Finish.
The Import dialog box closes.
The content of the selected DSS file is imported into the Signature Editor.
