4. Configuration

The configuration of the PERS target is done in userspace with the iptables command and an associated dynamic library for specific parameters. This library adds new options for setting up the PERS target; one of the options allows the user to specify a configuration file containing all the parameters needed to emulate a particular operating system. Hence by using different configuration files for each different netfilter rule, one can easily choose to look like a particular OS for some sources or destination addresses, for a specific interface, and/or for other matching criterias.

4.1 Command line options

Command line options are passed to the target when adding a rule using it, for instance with a syntax like the following one:

iptables -A <chain> -s <source> -d <destination> -j PERS <options>

[Refer to iptables documentation for more information on the global syntax]

The following options are recognized by the library:

• -tweak {src|dst} : This option sets the way packets should be rewritten for the corresponding rule. If its value is "src", then it means one wishes to protect the source of the matching packets (for instance, rewriting ISNs). If it is set do "dst", then the destination is protected (in that case acks would be rewritten).
• -local : This option specifies that either the source or the destination (depending on the value of tweak) is local, and that the "decoy" and "udp" modules should be enabled for it (if available in the configuration used) in order to completely fool tools suchs as nmap.
• -conf <file>: This option sets the configuration file to use for the emulated system in this rule (see below).

4.2 Configuration file

The parameters for emulation of a particular operating system are specified in the configuration file. This file has a syntax similar to named.conf, inspired from C. Options are grouped together in logical blocks (delimited with { and }), each block corresponding to a different kind of packet rewriting operation. Each option is composed of an identifier followed by one or more arguments, and ended by a ;. Options and blocks can be specified in any order.

Identification

The first item of the configuration file is an identification for the system being described. It is a string at most 20 characters long. Syntax is as follows:

 id "FakeOS";

Generic TCP parameters

These parameters are grouped together in a block named tcp. Example:

  tcp {
    incoming yes;
    outgoing no;
    max-window 65536;
  }

The incoming parameter sets whether you wish to enable TCP connections modifications (ISN, window size, options) for incoming connections to the protected zone. It can either be set to yes or no.

The outgoing parameter has the same meaning but for outgoing connections

The max-window parameter controls window size rewriting for TCP packets from connections matching the previous options. If it is set to a non-null value, then for every new connection with a window size greater than the given value, an offset is computed and applied to every packet to set the window size below the specified value for the length of the connection.

Sequence Numbers Generator Parameters

These parameters are grouped together in a block named tcp_isn. Example:

  tcp_isn {
    type random-inc 10000;
    initial-value 2600;
  }

The type parameter sets the type of generator to emulate and possible options for it. The following types are supported:

• fixed-inc <number> : That's the simplest generator. The initial sequence number is simply increased of a fixed value (specified as argument) at each new connection. Using 0 as the increment value allows one to emulated systems using fixed initial sequence numbers.
• random-inc <number> : That's a pseudo-random generator. For each new connection, the initial sequence number is incremented by a random value chosen between 0 and the specified number. This is the kind of generator used on systems such as Linux, FreeBSD, ... The strength of such a generator is determined by its random range.
• true-random : This is a truly random generator. For each new connection, the initial sequence number is randomly chosen using the kernel's internal entropy based random generator.
• builtin : This is the host system builtin generator. Hence under linux, it is a random incremented generator.
• time-dep <number> : This is a time dependant generator. The passes number specifies the frequency of the generator (in Hz). For instance, using 25000 for the value allows one to implement the generator recommended in RFC 793: the ISN is then incremented by 1 every 4 micro-seconds. (however, the generator granularity depends on the host system ticks precision, 100 Hz by default on linux/x86)

The initial-value sets the initial value to use for the emulated generator. A numeric value can be specified or random which will pick this number randomly when loading the rule. This parameter is of little importance on strong generators.

IP ID Generator Parameters

These parameters are grouped together in a block named ip_id. Example:

  ip_id {
    type broken-inc 1;
    initial-value 2600;
  }

The type parameter sets the type of generator to emulate and possible options for it. The same types as for the ISN generator are available, with an additional one, broken-inc number: it is an incremented counter of the specified value, but the result is saved in the packet in little endian order instead of network order.

Options Reordering Parameters

These parameters are grouped together in a block named tcp_options. Example:

  tcp_options {
    keep-unknown yes;
    keep-unused no;
    isolated-packets yes;
    timestamp-scale 100;
    code {
      <code...>
    }
  }

This block defines how TCP options of a packet should be rewritten. The code subsection contains a simple program written in a langage close to C (see below), which is compiled by the libipt_PERS.so module. This code is passed to the virtual machine that fills an option buffer (part of its state) as it runs it. When the execution is over, the new options buffer is used to replace the original options buffer of the packet.

The keep-unknown parameter specifies if "unknown" options in the original packet (hence that can't be handled in the code) should be added at the end of the new options buffer so they are kept. It can be set to either yes or no.

The keep-unused parameter specifies if options from the original packet that haven't been used (probed or copied) by the code should be added at the end of the new options buffer so they are kept. It can be set to either yes or no. This allows one to use a very simple code to reorder a few options while keeping the other ones functionnal.

The isolated-packets parameter specifies if options reordering should be performed for packets that do not belong to any known connection. It can be set to either yes or no. (defaults to no).

The timestamp-scale parameter specifies if the timestamp options of TCP packets related to the local machine should be changed to a new frequency. Its argument is the new frequency to use. (if it is null or equal to the base frequency it is ignored).

TCP decoying Parameters

These parameters are grouped together in a block named tcp_decoy. Example:

  tcp_decoy {
    code {
      <code...>
    }
  }

This block only contains a code subsection like the previous one, that defines tests to perform on packets in order to recognize pathological packets from analysis tools and decide the way to handle them. The language used is the same as before (see below).

UDP Decoying Parameters

These parameters are grouped together in a block named udp_unreach. Example:

  udp_unreach {
    reply yes;
    df no;
    max-len 56;
    tos 0;
  
    mangle-original {
      ip-len 21;
      ip-id same;
      ip-csum zero;
      udp-len 308;
      udp-csum zero;
      udp-data same;
    }
  }

The reply parameter sets if you want an ICMP "port unreachable" message to be sent when receiving an UDP datagram for a port not listening. It can be set to either yes or no. The other parametres of this block only apply if this is enabled.

The df parameters specifies whether the "Don't Fragment" bit should be set on generated ICMP messages.

The max-len parameter specifies the maximum length of the generated ICMP messages.

The tos parameters specifies the value for the "Type Of service" field of the IP header of the generated ICMP messages.

When sending an ICMP "port unreachable" message, part of the original packet is sent back along. The mangle-original subsection specify how this part should be handled and mangled. The following parameters are available:

• ip-len {same|<number>} : sets the changes to apply to the length field of the original packet IP header. It can be set to same (in that case it is unchanged) or to any numeric value (in that case it is replaced).
• ip-id {same|mangle|zero} : sets the changes to apply to the id field of the original packet IP header. It can be set to same, zero (then it is set to zero), mangle (it is changed for a different value).
• ip-csum {same|mangle|zero} : sets the changes to apply to the checksum of the original packet IP header. It can be set to same, zero, mangle.
• udp-len {same|<number>} : sets the changes to apply to the length field of the original packet UDP header. It can be set to same or to any numeric value.
• udp-csum {same|mangle|zero} : sets the changes to apply to the checksum of the original packet UDP header. It can be set to same, zero, mangle.
• udp-data {same|mangle|zero} : sets changes to apply to the first byte of the original UDP datagram payload. It can be set to same, zero, mangle.

4.3 Language

The tcp_options and tcp_decoy blocks both have a code subsection that can contain a program. As seen previously, this program is compiled by the dynamic library extending iptables into pseudo-code that is interpreted in the kernel module by a simple virtual machine. It operates over a TCP packet and handles an internal state, composed of the following:

• A TCP options buffer
• Several "registers": flags, mss, wscale, win, ack and df corresponding to the TCP header fields of the same name for a potential reply packet.

Code from the tcp_options subsection is applied to an incoming TCP packet, and after running the program the options buffer from the virtual machine state is used as the new options buffer for that packet.

Code from the tcp_decoy section is also applied to an incoming TCP packet, but the packet is not modifed. Depending on the result of running the program a new packet can be built from the state of the virtual machine and sent to the source of the original packet. The original packet can also be dropped, or passed as is to the next rules.

These programs are written in a language close to C. Some conditionnal tests can be performed on the original packets in order to adjust behavior depending on its contents/status

A test looks like:

  if (test) {
    <action>
  }

  if (test) {
    <action>
  } else {
    <action>
  }

A test is composed of one or more conditions, separated by logical operators && and ||, and grouped together with parentheses where needed. The following conditions are available:

• option(opt) : True if option opt is found in the original packet.
• flags(flag) : True if flag is enabled in the TCP header flags.
• flags(flag1&flag2&...) : True if all the specified flags are enabled in the TCP header flags.
• flags(flag1|flag2|...) : True if at least one of the specified flags is enabled in the TCP header flags.
• ack(val) : True if the TCP header ACK field has the value val.
• listen : True if the destination port is listening on the local host.

The language has several instructions to handle the internal state of the virtual machine:

• copy(opt) : This copies the opt option from the original packet to the options buffer of the state of the virtual machine, if such an option is found in the original packet.
• insert(opt, val) This inserts the opt option in the options buffer, with the specified value. A numeric value can be passed, or an expression like this + <number> which will give the option its original value incremented of the specified value. Only the mss, wscale and timestamp (in that case "this" means the current value usable as a local timestamp) options are supported by this instruction.
• insert(opt) : same as insert(opt, this).
• set(arg, val) : This sets one of the internal registers of the virtual machine. The available registers are flags, df, win and ack. For flags, the argument must be a valid combination of TCP flags, like for the tests. The df and win registers can have their value defined relatively to the original packet value by using the this + <number> construct seen above. This is also available for the ack register but then the final value is relative to the original packet sequence number (and not to its ack value).
• drop, accept, and reply: These instructions stop execution of the program by respectively dropping the packet, let it pass it to next rule, and build an answer from the virtual machine state and send it back. The default action is accept at the end of the code.

Hence, such a language allows one to precisely define behavior to reorder options, and also to generate appropriate replies for pathological tests from network analysis tools.

But we can notice the following points:

• Since the code in the tcp_option subsection only applies to options reordering, only the options buffer from the state of the virtual machine is used after running the program. Hence the listen and ack tests, and the insert, set, drop, reply instructions have little interest in this case.
• The options supported by the different tests and conditions were extracted from various RFCs specifiyng them; here are the names of the supported ones: eol, nop, mss, wscale, sackOK, sack, echo, echoreply, timestamp, pocOK, pocSP, CC, CC.NEW, CC.ECHO, acreq, acdata.
• The TCP flags supported by the different tests and conditions span the whole 12 bits usable and are coded with the following names: (from the lowest bit to the highest one): fin, syn, rst, push, ack, urg, ece, cwr, bog1, bog2, bog3, bog4.