diff options
-rw-r--r-- | packet_builder_yaml.asciidoc | 1340 | ||||
-rwxr-xr-x | yaml/headers.yaml | 79 |
2 files changed, 745 insertions, 674 deletions
diff --git a/packet_builder_yaml.asciidoc b/packet_builder_yaml.asciidoc index 5d824a58..d52ee4c8 100644 --- a/packet_builder_yaml.asciidoc +++ b/packet_builder_yaml.asciidoc @@ -1,670 +1,670 @@ -Packet Builder Language
-=======================
-:author: hhaim
-:email: <hhaim@cisco.com>
-:revnumber: 0.04
-:quotes.++:
-:numbered:
-
-== change log
-
-[options="header",cols="^1,^h,a"]
-|=================
-| Version | name | meaning
-| 0.01 | hhaim |
-- first version
-| 0.02 | hhaim
-|
-- change the bool fields to properties
-- add external/internal property
-- add const property ( instead cant_change)
-- change TLV property - now learn the prev header
-- add choice of next protocol that is not base on a field ( TCP->IP->TCP)
-| 0.03 | ybrustin
-|
-- add MAC address regexp
-- add gui_representation class with data_type, form_type, combobox_values, data_type_regexp items to describe GUI view of field
-- rename choice attribute to value_based_next_header
-- fixed some typos
-| 0.04 | ybrustin
-|
-- change value_based_next_header, combobox_values (to be consistent with value_based_next_header) to dictionary
-- added value_based_next_class for options
-- move 'help' attribute to gui_representation
-- add link to headers.yaml (references at bottom of the page)
-
-|=================
-
-
-== A file format for GUI packet builder
-
-=== Introduction
-
-We would like a file that will be read by GUI and will give us the ability to build packets using GUI
-
-The format should be *YAML*
-
-
-=== High Level Requirement
-
-* Define a YAML object format for dynamic building of packets and a program that change various fields
-* Ability to *parse* back the same buffer that was created using this tool (reversibility)
-** Ability to load packet from a pcap file and parse it
-* Ability to save the packet to a pcap file
-* Ability to save the packet and program in JSON format (same JSON-RPC format)
-* Set a value for any field of any protocol
-* Vary packet fields across packets at run time e.g. changing IP/MAC addresses
-* Stack protocols in any arbitrary order define in YAML format
-
-=== Header that should be supported (first phase)
-
-==== L2
-
-* Ethernet
-* 802.3
-* LLC SNAP
-* VLAN (with QinQ) stack
-* MPLS stack
-
-==== L3
-
-* ARP
-* IPv4
-* IPv6 (4x header)
-* IP-in-IP a.k.a IP Tunnelling (6over4, 4over6, 4over4, 6over6)
-
-==== L4
-
-* TCP
-* UDP
-* ICMPv4
-* ICMPv6
-* IGMP
-
-==== L7 anchor:Payload[]
-
-* Any text based protocol (HTTP, SIP, RTSP, NNTP etc.)
-** random string
-** repeat string
-
-* Pattern Binary
-** repeat of value (e.g 0x55)
-** random
-** seq (1,2,3,3,4)
-** User Hex Dump editor
-
-
-=== YAML Format
-
-==== Header section
-
-.Default Types anchor:Types[]
-[options="header",cols="1,2,3"]
-|=================
-| Field Name | meaning | size in bits
-| bit | describe the header object e.g tcp | 1
-| uint8 | describe the header object e.g tcp | 8
-| uint16 | the name in the GUI | 16
-| uint32 | sub fields of this header | 32
-| uint64 | sub fields of this header | 64
-| other class type | name of other class. for example, "c-mac-addr"; take fields from there, optionally overload them later | The size taken from that class
-| Payload | xref:Payload[Payload] | total packet size - all header until now
-| vlen_t | in case of varible size header this include the size to the end of varible size header see example xref:IpvOption[Ipv4Option] |total size of the object
-|=================
-
-
-.Default Data_Type anchor:Data_Type[]
-[options="header",cols="1,2"]
-|=================
-| Field Name | meaning
-| none | use Hex Editor as Types
-| ipv4_t | 4 decimals 0-255 each
-| mac_addr_t | ([0-9a-fA-F]\{2\}:)\{5\}[0-9a-fA-F]\{2\}
-| ipv4_mask_t | should match uint32 type
-| ipv6_t | should have 16 bytes field size 8x16
-| ipv6_mask_t | should have 16 bytes field size 8x16
-| another header class | sub fields of this header
-| char_t | array of bytes , look into the array_size of cost string
-| var_char_t | array based on a field value look into
-| regexp_t | define a Java function that converts a reg exp string to a buffer see here xref:GenRegExp[RegExp]
-|=================
-
-.Default Form_Type anchor:Form_Type[]
-[options="header",cols="1,3"]
-|=================
-| Field Name | meaning
-| none | simple editing field
-| combo_with_edit | combo box with predefined choices, can edit the field value manually
-| combo_without_edit | combo box with predefined choices, can [underline]#not# edit the field value manually
-| checkbox | toggle bits values, if item is array of bits, display several checkboxes per number of bits
-|=================
-
-
-.Default Gui_Representation anchor:Gui_Representation[]
-[options="header",cols="1,^1,5,^1,10"]
-|=================
-| Field Name | value type | meaning | Link | Additional info
-| help | string | the name in the GUI | |
-| data_type | string | how to represent data | xref:Data_Type[Data_Type] | data_type could get data_type_regexp e.g data_type = "ipv4"; data_type = "regexp" data_type_regexp = "string that define regexp and Java function"
-| form_type | string | which editing form to use | xref:Form_Type[Form_Type] | for example for ip address use combobox with option to edit value manually or choose: key "localhost" value "127.0.0.1" etc.
-| combobox_values | dictionary | pairs of 'key - value' for combo_with/without_edit | |
-| data_type_regexp | string | in case it is reg_exp the name of the function | xref:GenRegExp[GenRegExp] |
-|=================
-
-
-.Default Properties anchor:Properties[]
-[options="header",cols="1,7"]
-|=================
-| Field Name | meaning
-| ipv4_checksum | auto calculates checksum on this header Ipv4 type
-| tcp_checksum | calculate TCP checksum
-| udp_checksum | calculate UDP checksum
-| ipv4_total_length | calculate ipv4 total length this pkt_size = header + reset of packet
-| tlv | TLV length of the header (inlcudes the prev field length) example ip-option, tcp-option
-| le | little endian. deault is big
-| const | const field for example the 4 version of ipv4 header - this GUI won't give option to change this field
-| external | marks the header as an external header for the GUI. for example IPv4 is external header and mac-addr is internal header ( compose external header)
-|=================
-
-
-.Field_Type anchor:Field_Type[]
-[options="header",cols="1,^1,30,^1,^1,30"]
-|=================
-| Field Name | value type | meaning | Default Value | Link | Example
-| class | string | describe the class type | in case class is defined no need to have name and vise versa | | class : tcp
-| name | string | describe the instance name | in case class is defined no need to have name and vise versa | | name : tcp
-| array_size | integer | how many objects of this type, default value is 1 | 1 | | array_size : 6 in case of mac-addr
-| type | string | type, see Types define the size | "uint8_t" | xref:Types[Types] | type : "uint32_t" type : "mac_addr"
-| gui_representation | dictionary | description of how to view/edit data in GUI | | xref:Gui_Representation[Gui_Representation] | xref:Gui_Representation_Example[Gui_Representation_Example]
-| default | array/value | default value in the packets , you can override value for subfields in parent see example
-| [0 ]x header size | | xref:Overide_Subfields_Example[Overide_Subfields_Example]
-| properies | array of string like masks
-| properies of this fields | [] | xref:Properties[Properties] | ["le","external"] , ["tlv","le","const"]
-| value_based_next_header | dictionary | define the next protocol based on a field value | none | xref:Value_Based_Next_Header[Value_Based_Next_Header] |
-| value_based_next_class | dictionary | define the next class based on a field value (useful for options) | none | xref:Value_Based_Next_Class[Value_Based_Next_Class] |
-| next_headers | string or type | a name of class that define the next or just an array | "none" | xref:Next_headers[Next_headers] |
-| fields | array | array of Field_Type | [] | | fields : [ ]
-| offset | integer/string | offset into the packet in bits, in case of auto add base of prev fields | "auto" | |
-| option | string | a java code that define a way to calculate varible size | "none" | | |
-|=================
-
-
-.Field_Type anchor:ConstHeadesClass[]
-[options="header",cols="^1,^10"]
-|=================
-| Field Name | value type
-| "root" | the root pointer to the start of blocks L2/802.3 etc
-| "end" | end TLV headers
-| "payload" | the rest of the packets as buffer/string etc
-|=================
-
-
-.Next_headers anchor:Next_headers[]
-Example of Next_headers
-[source,python]
-----
-
- - class : "next-example-t-1"
- gui_representation:
- help : "next-example-t-1"
- next_headers : ["ipv4", "ipv6, "tcp"]
-
-# option 1 define in the header itself
- - class : "tcp"
- gui_representation:
- help : "TCP header"
- properies : ["external"]
- next_headers : ["ipv4", "ipv6, "tcp"]
- fields :
- - name : "ver"
-
-# option 2 define throw a class
- - class : "tcp"
- gui_representation:
- help : "TCP header"
- properies : ["external"]
- next_headers : "next-example-t-1" #
- fields :
- - name : "ver"
-----
-
-
-.Value_Based_Next_Header anchor:Value_Based_Next_Header[]
-Example of value_based_next_header
-[source,python]
-----
- value_based_next_header:
- 0x0800: 'ipv4'# name of an external or internal class , the GUI should distinct betwean internal and external
- 0x0806: 'arp'
- 0x86DD: 'ipv6'
- 0x8100: 'vlan'
- 0x8847: 'mpls unicast'
- default: 'payload' # if no match for any of above
-
-----
-
-
-.Generic RegExp Edit Field anchor:GenRegExp[]
-
-This will define a regexp that match for user input and how to converts it to buffer of bytes
-
-[source,python]
-----
-
-class MyClass : public RegExpBase {
- public:
-
-
- string get_reg_exp_string( ) {
- return ((\d){1-3})[.]((\d){1-3})[.]((\d){1-3})[.]((\d){1-3}))
- }
-
- # in case of match
- buffer get_buffer(){
- g= [get_group()[1].to_int()*256,get_group()[1].to_int()]
- # return list
- return (g)
- }
-
-}
-
-----
-
-
-
-==== Relations between object headers
-
-There would be a root object to point to possible starting headers
-
-
-[source,python]
-----
-
-- class : "root"
- gui_representation:
- help : "Root"
- next_headers : [ "ethernet", "llc", "_802-3"]
-----
-
-So in a way you could define a tree like this
-
-[source,python]
-----
-
-root -> L2 ( Ethernet , 802.3 , LLC SNAP )
- |( by field )
- |
- ------------------------------------- ( VLAN (with QinQ), MPLS , ipv4, ipv6, ARP , ICMP )
- | | | |
- | ipv4/ipv6 - -
- | |
- | |
- [Possibility - Ethernet/802.3/LLC SNAP) | UDP/TCP/Pyload
- Object | |
- for each option there tree of all the option --- -
-----
-
-
-==== Rules
-
-* The size of the header and offset is automatically defined in default by the order of the fields ( inc by type size multiply by array_size)
-* It can be overrided by offset field ( put offset in the object ) and then an more advanced field can be shown earlier in the GUI
-* The packet size is defined before the headers. Header Should not be allowed to be added if the size + header size is bigger than packet size
-* "Payload" is predefined Fields that take the reset of the packet and user can edit it ( see xref:Payload[Payload] )
-* There would be a spare field in the Stream object so GUI could add more metadata for reconstructing the builder types
- for example in this example Ethrenet/IP/TCP/IP/TCP you can't extrac from buffer alone that Payload is IP/TCP only the builder known that in build time.
-* Ip total length need to keep the total_pkt_size - this ip header . this should work for internal header too.
-* When GUI add header ("external") the total size of this header should be calculated ( varible size should be given a default - ipv4)
-
-
-=== Examples
-
-
-==== TLV (Ip option) anchor:IpvOption[], value_based_next_class anchor:Value_Based_Next_Class[]
-
-
-IP-option see link:http://tools.ietf.org/html/rfc791[ip_option]
-
-0 : END
-
-1 : Length 1
-
-other : Byte : Length ( +first) |option
-
-
-
-[source,python]
-----
-
- - class : "ip_option_131"
- gui_representation:
- help : "ip_option"
- fields :
- - name : "length" # tree with leaf of bits
- gui_representation:
- help : "length"
- type : uint8
- properties : ["tlv"] # the length include the prev field size (8 byte)
-
- - name : "pointer" # tree with leaf of bits
- type : uint8
-
- - name : "buffer" # tree with leaf of bits
- type : "tlv_reset"
-
- - class : "default_ip4_option_tlv"
- gui_representation:
- help : "ip_option"
- fields :
- - name : "length" # tree with leaf of bits
- gui_representation:
- help : "length"
- type : uint8
- properties : "tlv" # the length include the prev field size (8 byte)
-
- - name : "buffer" # tree with leaf of bits
- type : "vlen_t"
-
-
- - class : "ip_option"
- gui_representation:
- help : "ip_option"
- type : uint8
- default : [0x01]
- value_based_next_class :
- 0x00 : "end" # reserve name for ending the loop
- 0x01 : "ip_option" # back to this header
- 0x131 : "ip_option_131"
- 0x0812: "gre"
- default : "default_ip4_option_tlv"
-
-
-----
-
-* case of varible length field ip_option example
-
-
-
-==== Example TCP/IP
-
-
-[source,python]
-----
-
- - class : "c-mac-addr"
- type : "uint8"
- array_size : 6
- default : [0x00, 0x00, 0x01, 0x00, 0x00, 0x00]
- gui_representation:
- data_type : "mac-addr_t" # format ([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}
- help : "Mac addrees"
-
-
- - class : "ethernet"
- gui_representation:
- help : "Ethernet-L2"
- properties: ['external']
- fields :
- - name : "Dst"
- gui_representation:
- help : "destination mac"
- type : "c-mac-addr"
-
- - name : "Src"
- gui_representation:
- help : "source mac"
- type : "c-mac-addr"
-
- - name: "Ethertype"
- gui_representation:
- help: "Ethertype"
- type: "uint16"
- default: [0x0800]
- value_based_next_header :
- 0x0800 : "ipv4"
- 0x86DD : "ipv6"
- 0x8100 : "vlan"
- 0x8847 : "mpls" #unicast
- default : "payload"
-
-
- - class : "ipv4"
- gui_representation:
- help : "Ipv4"
- fields :
- - name : "ver"
- gui_representation:
- help : "Version"
- type : "bit"
- array_size : 4
- default : [0, 1, 0, 0]
- properties : ["const"]
-
- - name : "ihl"
- type : "bit"
- array_size : 4
- default : [0, 1, 1, 1]
- properties : ["ipv4_ihl"]
- gui_representation:
- help : "IHL"
- form_type: "checkbox"
-
- ..
-
- - name : "hdr_chsum"
- gui_representation:
- help : "Header Checksum"
- default : [0x00,0x00]
- properties : ["ipv4_check_sum", "const"]
-
- - name : "total_len"
- gui_representation:
- help : "Total Length"
- default : [0x00,0x00]
- properties : ["ipv4_total_len", "const"] # auto calculate total_size-offset_header
-
- - name : "protocol"
- type : uint8
- default : 0x06
- value_based_next_header : &ipv4_next_header
- 0x06 : "tcp"
- 0x11 : "udp"
- 0x29 : "ipv6"
- 0x2F : "gre"
- default : "payload"
- gui_representation:
- help : "IPv4 next Protocol"
- form_type: "combo_without_edit"
- combobox_values:
- <<: *ipv4_next_header # take same choices as value_based_next_header
-
- - name : "src_addr"
- type : uint32
- default : [16, 0, 0, 0]
- gui_representation:
- help : "Source Address"
- data_type : "ipv4" # reserve
-
- - name : "dst_addr"
- default : [48, 0, 0, 0]
- type : uint32
- gui_representation:
- help : "Destination Address"
- data_type : "ipv4" # reserve
- form_type : "combo_with_edit"
- combobox_values:
- [127, 0, 0, 1]: 'localhost'
- [255, 255, 255, 255]: 'broadcast'
-
-
- - class : "tcp"
- gui_representation:
- help : "TCP"
- properties : ["external"]
- fields :
- - name : "src_port"
- gui_representation:
- help : "Source Port"
- default : [0x30,0x00]
- type : uint16
-
- - name : "dest_port"
- gui_representation:
- help : "Source Port"
- default : [0x30,0x00]
- type : uint16
-
- - name : "seq"
- gui_representation:
- help : "Seq Number"
- type : uint32
- default : [0x30,0x00,00,00]
-
- - name : "ack"
- gui_representation:
- help : "Ack Number"
- type : uint32
- default : [0x30,0x00,00,00]
-
- ...
-
- - name : "flags" # tree with leaf of bits
- gui_representation:
- help : "Ack Number"
- type : uint8
- default : [0x30]
- fields :
- - name : "urg"
- help : "URG"
- type : bit
- default : [0x0]
-
- - name : "ack"
- help : "ACK"
- type : bit
- default : [0x1]
- ..
-
- - name : "checksum"
- gui_representation:
- help : "TCP Checksum"
- type : uint16
- default : [0x00,0x00]
- properties : ["tcp_checksum"] # auto calculate total_size-offset_header
-
-
-- class : "root" # reserve
- gui_representation:
- help : "Root"
- next_headers : [ "ethrenet" ,"llc","_802-3"]
----------------------------
-
-
-==== Overide subfields example anchor:Overide_Subfields_Example[]
-
-In this example parent class default value overrides default values of sub-fields ( 2 different mac-addr)
-
-[source,python]
-----
-
- - class : "c-mac-addr"
- type : "uint8"
- array_size : 6
- gui_representation:
- help : "Mac addrees"
- data_type : "mac-addr_t" # format ([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}
- default : [0x00,0x00,0x01,0x00,0x00,0x00]
-
-
- - class : "ethernet"
- gui_representation:
- help : "Ethernet-L2"
- properties : ["external"]
- default : [0x00,0x01,0x01,0x00,0x00,0x00, 0x00,0x02,0x02,0x00,0x00,0x00 ,0x08,00] # change the default of sub-fields . it is const size
- fields :
- - name : "Dst"
- gui_representation:
- help : "destination mac"
- type : "c-mac-addr"
-
- - name : "Src"
- gui_representation:
- help : "source mac"
- type : "c-mac-addr"
-
- - name : "ip_protocol"
- type : "uint16_t"
- default : [0x08,0x00]
- value_based_next_header :
- 0x0800 : "ipv4"
- 0x86DD : "ipv6"
- 0x8100 : "vlan"
- 0x8847 : "mpls unicast"
- default : "payload"
-----
-
-==== Gui Representation example anchor:Gui_Representation_Example[]
-[underline]#In YAML:#
-[source,python]
-----
- - name: 'Flags'
- type: 'bit'
- array_size: 3
- gui_representation:
- help: 'IPv4 Flags'
- form_type: 'checkbox' # can check each bit
-
-
- - name: 'dst_addr'
- default: [48, 0, 0, 0]
- type: uint32
- gui_representation:
- help: 'IPv4 Destination Address'
- data_type: 'ipv4_t' # special representation case, show as 4 decimal numbers
- form_type: 'combo_with_edit' # can choose from pre-defined values or edit manually
- combobox_values:
- [127, 0, 0, 1]: 'localhost'
- [255, 255, 255, 255]: 'broadcast'
-
-
- - name: 'protocol'
- type: uint8
- default: 0x06
- value_based_next_header: &ipv4_next_header
- 0x06: 'tcp'
- 0x11: 'udp'
- default : "payload"
- gui_representation:
- help: 'IPv4 Protocol Field'
- form_type: 'combo_without_edit' # choose from supported protocols, no manual edit
- combobox_values:
- <<: *ipv4_next_header # take same choices as value_based_next_header
-----
-
-[underline]#In GUI:#
-
-checkbox for bits:
-
-image:images/checkbox.jpg[]
-
-editing in combo-box:
-
-image:images/combo_button_editing.jpg[]
-
-choosing from predefined values:
-
-image:images/combo_button_choosing.jpg[]
-
-==== Union base
-
-TBD
-
-
-
-=== Resource
-* link:yaml/headers.yaml[headers.yaml]
-* link:https://wireedit.com/[WireEdit]
-* link:http://ostinato.org/[ostinato]
-* link:http://www.slideshare.net/nlekh/ixiaexplorer[IxExplorer]
-
-
+Packet Builder Language +======================= +:author: hhaim +:email: <hhaim@cisco.com> +:revnumber: 0.04 +:quotes.++: +:numbered: + +== change log + +[options="header",cols="^1,^h,a"] +|================= +| Version | name | meaning +| 0.01 | hhaim | +- first version +| 0.02 | hhaim +| +- change the bool fields to properties +- add external/internal property +- add const property ( instead cant_change) +- change TLV property - now learn the prev header +- add choice of next protocol that is not base on a field ( TCP->IP->TCP) +| 0.03 | ybrustin +| +- add MAC address regexp +- add gui_representation class with data_type, form_type, combobox_values, data_type_regexp items to describe GUI view of field +- rename choice attribute to value_based_next_header +- fixed some typos +| 0.04 | ybrustin +| +- change value_based_next_header, combobox_values (to be consistent with value_based_next_header) to dictionary +- added value_based_next_class for options +- move 'help' attribute to gui_representation +- add link to headers.yaml (references at bottom of the page) + +|================= + + +== A file format for GUI packet builder + +=== Introduction + +We would like a file that will be read by GUI and will give us the ability to build packets using GUI + +The format should be *YAML* + + +=== High Level Requirement + +* Define a YAML object format for dynamic building of packets and a program that change various fields +* Ability to *parse* back the same buffer that was created using this tool (reversibility) +** Ability to load packet from a pcap file and parse it +* Ability to save the packet to a pcap file +* Ability to save the packet and program in JSON format (same JSON-RPC format) +* Set a value for any field of any protocol +* Vary packet fields across packets at run time e.g. changing IP/MAC addresses +* Stack protocols in any arbitrary order define in YAML format + +=== Header that should be supported (first phase) + +==== L2 + +* Ethernet +* 802.3 +* LLC SNAP +* VLAN (with QinQ) stack +* MPLS stack + +==== L3 + +* ARP +* IPv4 +* IPv6 (4x header) +* IP-in-IP a.k.a IP Tunnelling (6over4, 4over6, 4over4, 6over6) + +==== L4 + +* TCP +* UDP +* ICMPv4 +* ICMPv6 +* IGMP + +==== L7 anchor:Payload[] + +* Any text based protocol (HTTP, SIP, RTSP, NNTP etc.) +** random string +** repeat string + +* Pattern Binary +** repeat of value (e.g 0x55) +** random +** seq (1,2,3,3,4) +** User Hex Dump editor + + +=== YAML Format + +==== Header section + +.Default Types anchor:Types[] +[options="header",cols="1,2,3"] +|================= +| Field Name | meaning | size in bits +| bit | describe the header object e.g tcp | 1 +| uint8 | describe the header object e.g tcp | 8 +| uint16 | the name in the GUI | 16 +| uint32 | sub fields of this header | 32 +| uint64 | sub fields of this header | 64 +| other class type | name of other class. for example, "c-mac-addr"; take fields from there, optionally overload them later | The size taken from that class +| Payload | xref:Payload[Payload] | total packet size - all header until now +| vlen_t | in case of varible size header this include the size to the end of varible size header see example xref:IpvOption[Ipv4Option] |total size of the object +|================= + + +.Default Data_Type anchor:Data_Type[] +[options="header",cols="1,2"] +|================= +| Field Name | meaning +| none | use Hex Editor as Types +| ipv4_t | 4 decimals 0-255 each +| mac_addr_t | ([0-9a-fA-F]\{2\}:)\{5\}[0-9a-fA-F]\{2\} +| ipv4_mask_t | should match uint32 type +| ipv6_t | should have 16 bytes field size 8x16 +| ipv6_mask_t | should have 16 bytes field size 8x16 +| another header class | sub fields of this header +| char_t | array of bytes , look into the array_size of cost string +| var_char_t | array based on a field value look into +| regexp_t | define a Java function that converts a reg exp string to a buffer see here xref:GenRegExp[RegExp] +|================= + +.Default Form_Type anchor:Form_Type[] +[options="header",cols="1,3"] +|================= +| Field Name | meaning +| none | simple editing field +| combo_with_edit | combo box with predefined choices, can edit the field value manually +| combo_without_edit | combo box with predefined choices, can [underline]#not# edit the field value manually +| checkbox | toggle bits values, if item is array of bits, display several checkboxes per number of bits +|================= + + +.Default Gui_Representation anchor:Gui_Representation[] +[options="header",cols="1,^1,5,^1,10"] +|================= +| Field Name | value type | meaning | Link | Additional info +| help | string | the name in the GUI | | +| data_type | string | how to represent data | xref:Data_Type[Data_Type] | data_type could get data_type_regexp e.g data_type = "ipv4"; data_type = "regexp" data_type_regexp = "string that define regexp and Java function" +| form_type | string | which editing form to use | xref:Form_Type[Form_Type] | for example for ip address use combobox with option to edit value manually or choose: key "localhost" value "127.0.0.1" etc. +| combobox_values | dictionary | pairs of 'key - value' for combo_with/without_edit | | +| data_type_regexp | string | in case it is reg_exp the name of the function | xref:GenRegExp[GenRegExp] | +|================= + + +.Default Properties anchor:Properties[] +[options="header",cols="1,7"] +|================= +| Field Name | meaning +| ipv4_checksum | auto calculates checksum on this header Ipv4 type +| tcp_checksum | calculate TCP checksum +| udp_checksum | calculate UDP checksum +| ipv4_total_length | calculate ipv4 total length this pkt_size = header + reset of packet +| tlv | TLV length of the header (inlcudes the prev field length) example ip-option, tcp-option +| le | little endian. deault is big +| const | const field for example the 4 version of ipv4 header - this GUI won't give option to change this field +| external | marks the header as an external header for the GUI. for example IPv4 is external header and mac-addr is internal header ( compose external header) +|================= + + +.Field_Type anchor:Field_Type[] +[options="header",cols="1,^1,30,^1,^1,30"] +|================= +| Field Name | value type | meaning | Default Value | Link | Example +| class | string | describe the class type | in case class is defined no need to have name and vise versa | | class : tcp +| name | string | describe the instance name | in case class is defined no need to have name and vise versa | | name : tcp +| array_size | integer | how many objects of this type, default value is 1 | 1 | | array_size : 6 in case of mac-addr +| type | string | type, see Types define the size | "uint8_t" | xref:Types[Types] | type : "uint32_t" type : "mac_addr" +| gui_representation | dictionary | description of how to view/edit data in GUI | | xref:Gui_Representation[Gui_Representation] | xref:Gui_Representation_Example[Gui_Representation_Example] +| default | array/value | default value in the packets , you can override value for subfields in parent see example +| [0 ]x header size | | xref:Overide_Subfields_Example[Overide_Subfields_Example] +| properies | array of string like masks +| properies of this fields | [] | xref:Properties[Properties] | ["le","external"] , ["tlv","le","const"] +| value_based_next_header | dictionary | define the next protocol based on a field value | none | xref:Value_Based_Next_Header[Value_Based_Next_Header] | +| value_based_next_class | dictionary | define the next class based on a field value (useful for options) | none | xref:Value_Based_Next_Class[Value_Based_Next_Class] | +| next_headers | string or type | a name of class that define the next or just an array | "none" | xref:Next_headers[Next_headers] | +| fields | array | array of Field_Type | [] | | fields : [ ] +| offset | integer/string | offset into the packet in bits, in case of auto add base of prev fields | "auto" | | +| option | string | a java code that define a way to calculate varible size | "none" | | | +|================= + + +.Field_Type anchor:ConstHeadesClass[] +[options="header",cols="^1,^10"] +|================= +| Field Name | value type +| "root" | the root pointer to the start of blocks L2/802.3 etc +| "end" | end TLV headers +| "payload" | the rest of the packets as buffer/string etc +|================= + + +.Next_headers anchor:Next_headers[] +Example of Next_headers +[source,python] +---- + + - class : "next-example-t-1" + gui_representation: + help : "next-example-t-1" + next_headers : ["ipv4", "ipv6, "tcp"] + +# option 1 define in the header itself + - class : "tcp" + gui_representation: + help : "TCP header" + properies : ["external"] + next_headers : ["ipv4", "ipv6, "tcp"] + fields : + - name : "ver" + +# option 2 define throw a class + - class : "tcp" + gui_representation: + help : "TCP header" + properies : ["external"] + next_headers : "next-example-t-1" # + fields : + - name : "ver" +---- + + +.Value_Based_Next_Header anchor:Value_Based_Next_Header[] +Example of value_based_next_header +[source,python] +---- + value_based_next_header: + 0x0800: 'ipv4'# name of an external or internal class , the GUI should distinct betwean internal and external + 0x0806: 'arp' + 0x86DD: 'ipv6' + 0x8100: 'vlan' + 0x8847: 'mpls unicast' + default: 'payload' # if no match for any of above + +---- + + +.Generic RegExp Edit Field anchor:GenRegExp[] + +This will define a regexp that match for user input and how to converts it to buffer of bytes + +[source,python] +---- + +class MyClass : public RegExpBase { + public: + + + string get_reg_exp_string( ) { + return ((\d){1-3})[.]((\d){1-3})[.]((\d){1-3})[.]((\d){1-3})) + } + + # in case of match + buffer get_buffer(){ + g= [get_group()[1].to_int()*256,get_group()[1].to_int()] + # return list + return (g) + } + +} + +---- + + + +==== Relations between object headers + +There would be a root object to point to possible starting headers + + +[source,python] +---- + +- class : "root" + gui_representation: + help : "Root" + next_headers : [ "ethernet", "llc", "_802-3"] +---- + +So in a way you could define a tree like this + +[source,python] +---- + +root -> L2 ( Ethernet , 802.3 , LLC SNAP ) + |( by field ) + | + ------------------------------------- ( VLAN (with QinQ), MPLS , ipv4, ipv6, ARP , ICMP ) + | | | | + | ipv4/ipv6 - - + | | + | | + [Possibility - Ethernet/802.3/LLC SNAP) | UDP/TCP/Pyload + Object | | + for each option there tree of all the option --- - +---- + + +==== Rules + +* The size of the header and offset is automatically defined in default by the order of the fields ( inc by type size multiply by array_size) +* It can be overrided by offset field ( put offset in the object ) and then an more advanced field can be shown earlier in the GUI +* The packet size is defined before the headers. Header Should not be allowed to be added if the size + header size is bigger than packet size +* "Payload" is predefined Fields that take the reset of the packet and user can edit it ( see xref:Payload[Payload] ) +* There would be a spare field in the Stream object so GUI could add more metadata for reconstructing the builder types + for example in this example Ethrenet/IP/TCP/IP/TCP you can't extrac from buffer alone that Payload is IP/TCP only the builder known that in build time. +* Ip total length need to keep the total_pkt_size - this ip header . this should work for internal header too. +* When GUI add header ("external") the total size of this header should be calculated ( varible size should be given a default - ipv4) + + +=== Examples + + +==== TLV (Ip option) anchor:IpvOption[], value_based_next_class anchor:Value_Based_Next_Class[] + + +IP-option see link:http://tools.ietf.org/html/rfc791[ip_option] + +0 : END + +1 : Length 1 + +other : Byte : Length ( +first) |option + + + +[source,python] +---- + + - class : "ip_option_131" + gui_representation: + help : "ip_option" + fields : + - name : "length" # tree with leaf of bits + gui_representation: + help : "length" + type : uint8 + properties : ["tlv"] # the length include the prev field size (8 byte) + + - name : "pointer" # tree with leaf of bits + type : uint8 + + - name : "buffer" # tree with leaf of bits + type : "tlv_reset" + + - class : "default_ip4_option_tlv" + gui_representation: + help : "ip_option" + fields : + - name : "length" # tree with leaf of bits + gui_representation: + help : "length" + type : uint8 + properties : "tlv" # the length include the prev field size (8 byte) + + - name : "buffer" # tree with leaf of bits + type : "vlen_t" + + + - class : "ip_option" + gui_representation: + help : "ip_option" + type : uint8 + default : [0x01] + value_based_next_class : + 0x00 : "end" # reserve name for ending the loop + 0x01 : "ip_option" # back to this header + 0x131 : "ip_option_131" + 0x0812: "gre" + default : "default_ip4_option_tlv" + + +---- + +* case of varible length field ip_option example + + + +==== Example TCP/IP + + +[source,python] +---- + + - class : "c-mac-addr" + type : "uint8" + array_size : 6 + default : [0x00, 0x00, 0x01, 0x00, 0x00, 0x00] + gui_representation: + data_type : "mac-addr_t" # format ([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2} + help : "Mac addrees" + + + - class : "ethernet" + gui_representation: + help : "Ethernet-L2" + properties: ['external'] + fields : + - name : "Dst" + gui_representation: + help : "destination mac" + type : "c-mac-addr" + + - name : "Src" + gui_representation: + help : "source mac" + type : "c-mac-addr" + + - name: "Ethertype" + gui_representation: + help: "Ethertype" + type: "uint16" + default: [0x0800] + value_based_next_header : + 0x0800 : "ipv4" + 0x86DD : "ipv6" + 0x8100 : "vlan" + 0x8847 : "mpls" #unicast + default : "payload" + + + - class : "ipv4" + gui_representation: + help : "Ipv4" + fields : + - name : "ver" + gui_representation: + help : "Version" + type : "bit" + array_size : 4 + default : [0, 1, 0, 0] + properties : ["const"] + + - name : "ihl" + type : "bit" + array_size : 4 + default : [0, 1, 1, 1] + properties : ["ipv4_ihl"] + gui_representation: + help : "IHL" + form_type: "checkbox" + + .. + + - name : "hdr_chsum" + gui_representation: + help : "Header Checksum" + default : [0x00,0x00] + properties : ["ipv4_check_sum", "const"] + + - name : "total_len" + gui_representation: + help : "Total Length" + default : [0x00,0x00] + properties : ["ipv4_total_len", "const"] # auto calculate total_size-offset_header + + - name : "protocol" + type : uint8 + default : 0x06 + value_based_next_header : &ipv4_next_header + 0x06 : "tcp" + 0x11 : "udp" + 0x29 : "ipv6" + 0x2F : "gre" + default : "payload" + gui_representation: + help : "IPv4 next Protocol" + form_type: "combo_without_edit" + combobox_values: + <<: *ipv4_next_header # take same choices as value_based_next_header + + - name : "src_addr" + type : uint32 + default : [16, 0, 0, 0] + gui_representation: + help : "Source Address" + data_type : "ipv4" # reserve + + - name : "dst_addr" + default : [48, 0, 0, 0] + type : uint32 + gui_representation: + help : "Destination Address" + data_type : "ipv4" # reserve + form_type : "combo_with_edit" + combobox_values: + [127, 0, 0, 1]: 'localhost' + [255, 255, 255, 255]: 'broadcast' + + + - class : "tcp" + gui_representation: + help : "TCP" + properties : ["external"] + fields : + - name : "src_port" + gui_representation: + help : "Source Port" + default : [0x30,0x00] + type : uint16 + + - name : "dest_port" + gui_representation: + help : "Source Port" + default : [0x30,0x00] + type : uint16 + + - name : "seq" + gui_representation: + help : "Seq Number" + type : uint32 + default : [0x30,0x00,00,00] + + - name : "ack" + gui_representation: + help : "Ack Number" + type : uint32 + default : [0x30,0x00,00,00] + + ... + + - name : "flags" # tree with leaf of bits + gui_representation: + help : "Ack Number" + type : uint8 + default : [0x30] + fields : + - name : "urg" + help : "URG" + type : bit + default : [0x0] + + - name : "ack" + help : "ACK" + type : bit + default : [0x1] + .. + + - name : "checksum" + gui_representation: + help : "TCP Checksum" + type : uint16 + default : [0x00,0x00] + properties : ["tcp_checksum"] # auto calculate total_size-offset_header + + +- class : "root" # reserve + gui_representation: + help : "Root" + next_headers : [ "ethrenet" ,"llc","_802-3"] +--------------------------- + + +==== Overide subfields example anchor:Overide_Subfields_Example[] + +In this example parent class default value overrides default values of sub-fields ( 2 different mac-addr) + +[source,python] +---- + + - class : "c-mac-addr" + type : "uint8" + array_size : 6 + gui_representation: + help : "Mac addrees" + data_type : "mac-addr_t" # format ([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2} + default : [0x00,0x00,0x01,0x00,0x00,0x00] + + + - class : "ethernet" + gui_representation: + help : "Ethernet-L2" + properties : ["external"] + default : [0x00,0x01,0x01,0x00,0x00,0x00, 0x00,0x02,0x02,0x00,0x00,0x00 ,0x08,00] # change the default of sub-fields . it is const size + fields : + - name : "Dst" + gui_representation: + help : "destination mac" + type : "c-mac-addr" + + - name : "Src" + gui_representation: + help : "source mac" + type : "c-mac-addr" + + - name : "ip_protocol" + type : "uint16_t" + default : [0x08,0x00] + value_based_next_header : + 0x0800 : "ipv4" + 0x86DD : "ipv6" + 0x8100 : "vlan" + 0x8847 : "mpls unicast" + default : "payload" +---- + +==== Gui Representation example anchor:Gui_Representation_Example[] +[underline]#In YAML:# +[source,python] +---- + - name: 'Flags' + type: 'bit' + array_size: 3 + gui_representation: + help: 'IPv4 Flags' + form_type: 'checkbox' # can check each bit + + + - name: 'dst_addr' + default: [48, 0, 0, 0] + type: uint32 + gui_representation: + help: 'IPv4 Destination Address' + data_type: 'ipv4_t' # special representation case, show as 4 decimal numbers + form_type: 'combo_with_edit' # can choose from pre-defined values or edit manually + combobox_values: + [127, 0, 0, 1]: 'localhost' + [255, 255, 255, 255]: 'broadcast' + + + - name: 'protocol' + type: uint8 + default: 0x06 + value_based_next_header: &ipv4_next_header + 0x06: 'tcp' + 0x11: 'udp' + default : "payload" + gui_representation: + help: 'IPv4 Protocol Field' + form_type: 'combo_without_edit' # choose from supported protocols, no manual edit + combobox_values: + <<: *ipv4_next_header # take same choices as value_based_next_header +---- + +[underline]#In GUI:# + +checkbox for bits: + +image:images/checkbox.jpg[] + +editing in combo-box: + +image:images/combo_button_editing.jpg[] + +choosing from predefined values: + +image:images/combo_button_choosing.jpg[] + +==== Union base + +TBD + + + +=== Resource +* link:yaml/headers.yaml[headers.yaml] +* link:https://wireedit.com/[WireEdit] +* link:http://ostinato.org/[ostinato] +* link:http://www.slideshare.net/nlekh/ixiaexplorer[IxExplorer] + + diff --git a/yaml/headers.yaml b/yaml/headers.yaml index fd217dc6..14a94e56 100755 --- a/yaml/headers.yaml +++ b/yaml/headers.yaml @@ -22,7 +22,7 @@ gui_representation: help: 'Ethernet-L2' properties: ['external'] - default: [0x00, 0x01, 0x01, 0x00, 0x00, 0x00, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00, 0x08, 0x00] + default: [0x01, 0x01, 0x01, 0x00, 0x02, 0x02, 0x00, 0x02, 0x02, 0x00, 0x00, 0x00, 0x08, 0x00] fields: - name: 'Dst' gui_representation: @@ -42,9 +42,9 @@ default: 0x0800 value_based_next_header: 0x0800: 'ipv4' + 0x86DD: 'ipv6' # not implemented # 0x0806: 'arp' - # 0x86DD: 'ipv6' # 0x8100: 'vlan' # field of 4 bytes added in this case, what to do? # 0x8847: 'mpls unicast' # unicast or multicast? multicast is 0x8848 default: 'payload' @@ -148,8 +148,8 @@ value_based_next_header: &ipv4_next_header 0x06: 'tcp' 0x11: 'udp' + 0x29: 'ipv6' # not implemented - # 0x29: 'ipv6' # 0x2F: 'gre' default: 'payload' gui_representation: @@ -180,6 +180,67 @@ # help: 'IPv4 options' # type: 'c-ipv4-options' + + - class: 'ipv6' + gui_representation: + help: 'IPv6' + properties: ['external'] + fields: + - name: 'ver' + gui_representation: + help: 'Version' + type: 'c-bit' + array_size: 4 + default: [0, 1, 1, 0] + properties: ['const'] + + - name: 'traff_class/diff_serv' + gui_representation: + help: 'Traffic Class/Diff Serv' + type: 'bit' + array_size: 8 + default: [0, 0, 0, 0, 0, 0, 0, 0] + + - name: 'flow_label' + gui_representation: + help: 'Flow Label' + type: 'bit' + array_size: 20 + default: [0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1, 0, 1] + + - name: 'payload_length' + gui_representation: + help: 'Payload Length' + type: 'uint16' + default: 40 + + - name: 'ipv6_next_header' + gui_representation: + help: 'IPv6 Next Header field' + type: 'uint8' + value_based_next_header: + 6: 'tcp' + 17: 'udp' + 41: 'ipv6' + default: 'tcp' + + - name: 'hop_limit' + gui_representation: + help: 'IPv6 hop limit' + type: 'uint8' + default: 200 + + - name: 'Src' + gui_representation: + help: 'Source IPv6' + type: 'c-ipv6-addr' + + - name: 'Dst' + gui_representation: + help: 'Destination IPv6' + type: 'c-ipv6-addr' + + # L4 @@ -286,7 +347,7 @@ gui_representation: help: 'Window size' type: uint16 - default: 0x0000 + default: 0x0080 - name: 'checksum' gui_representation: @@ -375,6 +436,16 @@ help: 'bit with checkbox representation' form_type: 'checkbox' + + - class: 'c-ipv6-addr' + type: 'uint16' + array_size: 8 + default: [7, 8, 7, 8, 7, 8, 7, 8] + gui_representation: + help: 'IPv6 address' + data_type: 'ipv6_t' + form_type: 'combo_with_edit' + ###################### # incomplete |