SYNOPSIS

DESCRIPTION

This document describes the bittwiste program, the pcap(3) capture file editor. Bittwiste is designed to work only with Ethernet frame, e.g. link type DLT_EN10MB in pcap(3), with a maximum frame size of 1514 bytes which is equivalent to a MTU of 1500 bytes, 14 bytes for Ethernet header.

Bittwiste can currently edit Ethernet, ARP, IP, ICMP, TCP, and UDP headers. If run with the -X flag, you can append your own payload after any of these headers; specified using the -L and -T flag. Bittwiste will, if not run with the -C flag, recalculate the checksums for IP, ICMP, TCP, and UDP packets, except for the last fragment of a fragmented IP datagram; bittwiste does not currently support checksum correction for the last fragment of a fragmented IP datagram. While parsing the packets in a trace file, bittwiste will skip, i.e. write to output file as is, any truncated packet, for example, an ICMP packet with a captured length of 25 bytes (we need at least 28 bytes; 14 bytes for Ethernet header, minimum 20 bytes for IP header, and 4 bytes for ICMP header) does not give enough information on its ICMP header for bittwiste to read and modify it. In this case, you can utilize the -L and -T flag to copy the original packet up to its IP header and append your customized ICMP header and data to the packet using the -X flag. When specifying payload that covers the ICMP, TCP or UDP header and its data, you can use zeros, e.g. 0000 for 2 bytes of zeros, for the header checksum which is then corrected automatically by bittwiste.

In order to simplify the way options are specified, you can only edit packets of a specific type supplied to the -T flag per execution of bittwiste on a trace file. In addition, the -T flag must appear last among the general options which are the -I, -O, -L, -X, -C, -M, -D, -R and -S flag.

OPTIONS

-Iinput

Input pcap based trace file.

-Ooutput

Output trace file.

-Llayer

Copy up to the specified layer and discard the remaining data. Value for layer must be either 2, 3 or 4 where 2 for Ethernet, 3 for ARP or IP, and 4 for ICMP, TCP or UDP.

-Xpayload

Append payload in hex digits to the end of each packet. Example: -X 0302aad1-X flag is ignored if -L and -T flag are not specified.

Save only the packets within the specified timeframe with up to one-second resolution using DD/MM/YYYY,HH:MM:SS as the format for start and end time in timeframe. Example: -S 22/10/2006,21:47:35-24/10/2006,13:16:05-S flag is evaluated after -R flag.

-Theader

Edit only the specified header. Possible keywords for header are, eth, arp, ip, icmp, tcp, or udp. -T flag must appear last among the general options.

-h

Print version information and usage.

header-specific-options

Each packet that matches the type supplied to the -T flag is modified based on the options described below:

Options for eth (RFC 894):

-ddmac or omac,nmac

Destination MAC address. Example: -d 00:08:55:64:65:6a If omac and nmac are specified instead, all occurences of omac in the destination MAC address field will be replaced with nmac.

-ssmac or omac,nmac

Source MAC address. Example: -s 00:13:20:3e:ab:cf If omac and nmac are specified instead, all occurences of omac in the source MAC address field will be replaced with nmac.

-ttype

EtherType. Possible keywords for type are, ip and arp only.

Options for arp (RFC 826):

-oopcode

Operation code in integer value between 0 to 65535. For example, you can set opcode to 1 for ARP request, 2 for ARP reply.

-ssmac or omac,nmac

Sender MAC address. Example: -s 00:13:20:3e:ab:cf If omac and nmac are specified instead, all occurences of omac in the sender MAC address field will be replaced with nmac.

-psip or oip,nip

Sender IP address. Example: -p 192.168.0.1 If oip and nip are specified instead, all occurences of oip in the sender IP address field will be replaced with nip.

-ttmac or omac,nmac

Target MAC address. Example: -t 00:08:55:64:65:6a If omac and nmac are specified instead, all occurences of omac in the target MAC address field will be replaced with nmac.

-qtip or oip,nip

Target IP address. Example: -q 192.168.0.2 If oip and nip are specified instead, all occurences of oip in the target IP address field will be replaced with nip.

Options for ip (RFC 791):

-iid

Identification in integer value between 0 to 65535.

-fflags

Control flags. Possible characters for flags are:

- : remove all flagsr : set the reserved flagd : set the don't fragment flagm : set the more fragment flag

Example: -f d If any of the flags is specified, all original flags are removed automatically.

-ooffset

Fragment offset in integer value between 0 to 7770. Value for offset represents the number of 64-bit segments contained in earlier fragments which must not exceed 7770 (62160 bytes).

-tttl

Time to live in integer value between 0 to 255 (milliseconds).

-pproto

Protocol number in integer value between 0 to 255. Some common protocol numbers are:

For the complete list, see:http://www.iana.org/assignments/protocol-numbers

-ssip or oip,nip

Source IP address. Example: -s 192.168.0.1 If oip and nip are specified instead, all occurences of oip in the source IP address field will be replaced with nip.

-ddip or oip,nip

Destination IP address. Example: -d 192.168.0.2 If oip and nip are specified instead, all occurences of oip in the destination IP address field will be replaced with nip.

Options for icmp (RFC 792):

-ttype

Type of message in integer value between 0 to 255. Some common messages are:

0 : Echo reply3 : Destination unreachable8 : Echo11 : Time exceeded

For the complete list, see:http://www.iana.org/assignments/icmp-parameters

-ccode

Error code for this ICMP message in integer value between 0 to 255. For example, code for time exceeded message may have one of the following values:

0 : transit TTL exceeded1 : reassembly TTL exceeded

For the complete list, see:http://www.iana.org/assignments/icmp-parameters

Options for tcp (RFC 793):

-ssport or op,np

Source port number in integer value between 0 to 65535. If op and np are specified instead, all occurrences of op in the source port field will be replaced with np.

-ddport or op,np

Destination port number in integer value between 0 to 65535. If op and np are specified instead, all occurrences of op in the destination port field will be replaced with np.

-qseq

Sequence number in integer value between 0 to 4294967295. If SYN control bit is set, e.g. character s is supplied to the -f flag, seq represents the initial sequence number (ISN) and the first data byte is ISN + 1.

-aack

Acknowledgment number in integer value between 0 to 4294967295. If ACK control bit is set, e.g. character a is supplied to the -f flag, ack represents the value of the next sequence number that the receiver is expecting to receive.

Example: -f s If any of the flags is specified, all original flags are removed automatically.

-wwin

Window size in integer value between 0 to 65535. If ACK control bit is set, e.g. character a is supplied to the -f flag, win represents the number of data bytes, beginning with the one indicated in the acknowledgment number field that the receiver is willing to accept.

-uurg

Urgent pointer in integer value between 0 to 65535. If URG control bit is set, e.g. character u is supplied to the -f flag, urg represents a pointer that points to the first data byte following the urgent data.

Options for udp (RFC 768):

-ssport or op,np

Source port number in integer value between 0 to 65535. If op and np are specified instead, all occurrences of op in the source port field will be replaced with np.

-ddport or op,np

Destination port number in integer value between 0 to 65535. If op and np are specified instead, all occurrences of op in the destination port field will be replaced with np.

COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.