Wireless jamming model

General

Network Security Lab, University of Washington, Seattle has begun work on a wireless interference (jamming) model for ns3. The goal is to enable researchers to use ns3 to study jamming and its mitigation methods.

Project Background

Interference (Jamming) in wireless networks is an important example of malicious attacks in wireless networks. It is achieved by deliberate transmission of radio signals to disrupt the communication in a wireless network by decreasing the signal-to-interference-noise ratio (SINR). Jamming leads to corrupted packets at the receiver, which results in a lowered throughput.

Project Goals

• To provide a simulation toolkit that allows researchers to easily implement and simulate a wireless jamming strategy and jamming detection/mitigation strategy.
• To enable researchers to evaluate the performances of jamming and jamming detection/mitigation strategies.

This model focuses on modeling the intelligence layer (eg. deciding when and what packets to jam/interfere, deciding whether a node is being jammed/interfered, deciding how to mitigate jamming/interference). It uses existing channel (interference) model to simulate interference/noise in the wireless channel, and existing PHY models to send packets. Our design goal is to abstract the underlying wireless PHY layer protocol from the intelligence layer, so that the same strategy (jamming or jamming detection/mitigation) can be applied to any existing/developing ns-3 wireless PHY layer protocols without any change.

Schedule

• 5/1/2010 - now : Public review. Code available at: http://codereview.appspot.com/1055041/show
• 4/19/2010 - 4/30/2010 : Private review.

Jamming Model Hierarchy

Jamming model hierarchy

The jamming model is designed to minimize its dependency on the physical (PHY) layer of the wireless protocol. It consists of the following components:

• Jamming intelligence (jammer).
  • This base class provides interfaces to wireless module utility.
  • Detailed jamming strategies such as constant jammer, reactive jammer etc. are implemented in child classes.
  • This class depends on the wireless module utility class.

• Jamming detection/mitigation intelligence (mitigation).
  • This base class provides interfaces to wireless module utility.
  • Detailed jamming detection/mitigation strategies such as mitigate by channel hop, are implemented in child classes.
  • This class depends on the wireless module utility class.

• Wireless module utility (utility).
  • This class provides a set of functions for jammer and jamming mitigation classes to utilize for implementing their strategies.
  • This class acts as a bridge between the intelligence layer and the PHY layer, separating the intelligence from PHY layer details.

• PHY layer driver (driver).
  • Modification to PHY layer classes are required to provide interface to the utility.
  • The modifications are specific to the PHY layer class one wants to study.
  • Driver also notifies the Energy model, if installed.

Jamming Intelligence (Jammer)

Overview

Jammer class structure

The following types of jammers are provided by the jamming model:

• Eavesdropper jammer:
  • Listens and records wireless traffic in channel(s).
• Constant jammer:
  • Sends jamming signal of certain duration at a constant interval.
• Random jammer:
  • Sends jamming signal of certain duration at a randomly chosen interval.
• Reactive jammer:
  • Sends jamming signal of certain duration only when communication is present in the channel.

Users can easily define their own jamming strategies (classes) following the format in provided classes. The jamming intelligence class is designed to abstract the detail of sending jamming signals and extracting information from the channel.

Reactive jammer work flow

Public APIs

• StartJammer:
  • Starts the jammer. This function is scheduled to start the jammer (start sending jamming signal) at specified time.

• StopJammer:
  • Stops the jammer. Thus function is scheduled to stop the jammer (stop sending jamming signal) at specified time.

• StartRxHandler:
  • Callback function invoked at the beginning of Rx by WirelessModuleUtility to decided whether a packet is to be received.
  • A jammer node can decide whether it wants to receive the incoming packet.

• HandleIncomingPacket (EndRxhandler):
  • Callback function invoked at the end of Rx by WirelessModuleUtility.
  • This callback is used to pass the received packet to the jammer intelligence.

• EndTxHandler:
  • Callback function invoked at the end of Tx by WirelessModuleUtility.

• SetUtilityModule:
  • Sets pointer to WirelessUtilityModule installed on node, called by JammerHelper during installation.
  • Jammer class cannot operate without support of WirelessUtilityModule.

• SetEnergySource:
  • Sets pointer to EnergySource installed on node, called by JammerHelper during installation.

• SetNodeId:
  • Records current node ID, called by JammerHelper during installation.

Protected APIs

• Pointer to WirelessModuleUtility:
  • Used to expose various public APIs provided WirelessModuleUtility.

• IsJammerOn

• GetEnergyFraction:
  • Returns current node's energy fraction [0,1].
  • Used for energy aware jammers.

• GetNodeId:
  • Returns current node ID, used mainly for debug traces.

Jamming Detection/Mitigation

Overview

Jamming mitigation class structure. Classes in dotted boxes are not included in initial release.

The following jamming detection strategies are provided by the jamming model:

• Detect jamming by RSS.
• Detect jamming by PDR.
• Detect jamming by RSS & PDR.

The following jamming mitigation strategies are provided by the jamming model:

• Mitigate by channel hop.
  • When jamming is detected, honest nodes hop onto a different channel (given a multi-channel wireless protocol) to avoid being jammed.

Users can easily define their own jamming detection/mitigation strategies (classes) following the format in provided classes. The jamming detection/mitigation class is designed to abstract the detail of extracting information from the channel.

Mitigate by channel hop work flow.

Public APIs

• StartMitigation:
  • Starts jamming detection/mitigation.
  • This function is called automatically at the beginning of simulation. It can also be scheduled to restart jamming detection/mitigation.

• StopMitigation:
  • Stops jamming detection/mitigation.
  • This function is scheduled to stop jamming detection/mitigation.

• HandleIncomingPacket (EndRxhandler):
  • Callback function invoked at the end of Rx by WirelessModuleUtility.
  • This callback is used to pass the received packet to the jamming detection/mitigation intelligence.

• EndTxHandler:
  • Callback function invoked at the end of Tx by WirelessModuleUtility.

• SetUtilityModule:
  • Sets pointer to WirelessUtilityModule installed on node, called by JammingMitigationHelper during installation.
  • Jamming detection/mitigation class cannot operate without support of WirelessUtilityModule.

• SetEnergySource:
  • Sets pointer to EnergySource installed on node, called by JammingMitigationHelper during installation.

• SetNodeId:
  • Records current node ID, called by JammingMitigationHelper during installation.

Protected APIs

• Pointer to WirelessModuleUtility:
  • Used to expose various public APIs provided WirelessModuleUtility.

• IsMitigationOn

• GetEnergyFraction:
  • Returns current node's energy fraction [0,1].
  • Used for energy aware jamming mitigation strategies.

• GetNodeId:
  • Returns current node ID, used mainly for debug traces.

Wireless Module Utility

Overview

Wireless Module Utility work flow.

This class provides essential functions for jamming intelligence and jamming detection/mitigation intelligence to operate. It can also be installed separately for monitoring network performance such as throughput.

Callbacks are used to connect the Wireless Module Utility to the PHY layer and the intelligence layer (jamming, jamming detection/mitigation). By doing so, the Wireless Module Utility abstracts the underlying PHY layer protocol, providing unified APIs for different intelligence layer models. We hope this design will enable users to easily apply (without any change to the code) intelligence layer models to different PHY layer protocol.

Public APIs

• StartRxHandler:
  • Handles start of Rx. Returns true if the current packet is to be received.
  • Called by PHY layer driver at the beginning of Rx.
  • This function invokes StartRxHandler callback from either the jammer or jamming mitigation module. Passing on information at the begging of packet.
  • This function also updates network information such as RSS.

• EndRxHandler:
  • Handles end of Rx.
  • Called by PHY layer driver at the end of Rx.
  • This function invokes EndRxHandler callback from either the jammer or jamming mitigation module. Passing on information of the received packet.
  • This function also updates network information such as RSS, PDR and throughput.

• StartTxHandler:
  • Handles start of Tx.
  • Called by PHY layer driver at the beginning of Tx.
  • This function invokes StartTxHandler callback from either the jammer or jamming mitigation module.
  • This function also updates network information such as throughput.

• EndTxHandler:
  • Handles end of Tx.
  • Called by PHY layer driver at the end of Tx.
  • This function invokes EndTxHandler callback from either the jammer or jamming mitigation module.

• GetTotalBytesRx:
  • Returns total number of bytes received.

• GetTotalBytesTx:
  • Returns total number of bytes sent.

• GetRxThroughput:
  • Returns Rx throughput.

• GetTxThroughput:
  • Returns Tx throughput.

• GetPdr:
  • Returns Packet Delivery Ratio (PDR).
  • PDR is defined as: the ratio of packets that are successfully delivered to a destination compared to the number of packets that have been sent out by the sender.
  • PDR is calculated at the receiver side as: the ratio of the number of successfully received packets with respect to the number of packets preambles received.
  • A sliding window method is used for recording number of packets. The size of the PDR window is defined as an attribute of Wireless Module Utility.
  • The update of PDR is done internally in Wireless Module Utility whenever a new packet arrives.

• GetRss:
  • Returns Received Signal Strength (RSS) at current node.
  • PHY layer driver support is required for RSS recording.
  • RSS is updated periodically in Wireless Module Utility by querying the PHY layer (callback).
  • The RSS update interval is defined as an attribute of Wireless Module Utility.

• SendJammingSignal:
  • Sends jamming signal of certain power and duration (by invoking PHY layer callback).
  • Called by jammer classes to transmit jamming signal.

• SwitchChannel:
  • Switch current wireless channel to specified channel (by invoking PHY layer callback).
  • Called by jamming mitigation objects as a mitigation strategy.

• SendMitigationMessage:
  • Send special jamming mitigation message (by invoking PHY layer callback).
  • Called by jamming mitigation objects. Some mitigation methods require sending a control packets for coordinating mitigation efforts.

PHY Layer Driver

Overview

PHY Layer (NslWifiPhy) driver work flow.

Modifications of the PHY layer is required to pass information to/from the wireless module utility. Currently, we provide a modified YansWifiPhy class called NslWifiPhy as an example of how PHY layer driver can be implemented.

Driver Functions

PHY layer driver are usually private functions. It typically (based on implementation of YansWifiPhy) include the following functions:

• InitDriver:
  • Initializes driver. This may include setting up pointers to WirelessModuleUtility and DeviceEnergyModel objects.

• DriverStartTx:
  • This function calls StartTxHandler in WirelessModuleUtility.
  • It is usually inserted into SendPacket function of the PHY class.

• DriverEndTx:
  • This function calls EndTxHandler in WirelessModuleUtility.
  • It should be called at the end of Tx. In the case of NslWifiPhy (or YansWifiPhy) it is scheduled to be invoked at the end of Tx.

• DriverStartRx:
  • This function calls StartRxHandler in WirelessModuleUtility.
  • It is usually inserted into StartReceivePacket function of the PHY class.

• DriverEndRx:
  • This function calls EndRxHandler in WirelessModuleUtility.
  • It is usually inserted into EndRx function of the PHY class.

• UtilitySendPacket:
  • This is a wrapper function for SendPacket of the PHY class.
  • It is the callback invoked by SendJammingSignal and SendMitigationMessage function in WirelessModuleUtility.

• UpdatePhyLayerInfo:
  • This function passes information of the PHY layer (Tx power, Tx gain, Rx gain, data rate, number of channels, current channel etc.) to the WirelessModuleUtility.

• MeasureRss:
  • Measures current node RSS. In the case of NslWifiPhy (or YansWifiPhy), it is completed by querying InterferenceHelper.

Usage

A complete sample simulation script using all components for the Wireless Jamming Model is available here: File:Sample-script.patch

Jammer

The following code snippet installs a reactive jammer onto a node with modified wifi PHY (NslWifiPhy) already installed.

 /* create some nodes */ 
 NodeContainer c;
 c.Create(5);
 
 /* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */
 
 /* install jammer */
 JammerHelper jammerHelper;
 // configure jammer type
 jammerHelper.SetJammerType ("ns3::ReactiveJammer");
 // set jammer parameters
 jammerHelper.Set ("ReactiveJammerRxTimeout", TimeValue (Seconds (2.0)));
 jammerHelper.Set ("ReactiveJammerReactionStrategy",
                   UintegerValue(ReactiveJammer::FIXED_PROBABILITY));
 // enable jammer reaction to jamming mitigation
 jammerHelper.Set ("ReactiveJammerReactToMitigation", UintegerValue(true));
 // install jammer
 JammerContainer jammers = jammerHelper.Install (c.Get (4));

Note that the jammer class cannot operate without installing the WirelessModuleUtility class, thus it is automatically installed by the JammerHelper. We recommend to install the WirelessModuleUtility class separately before installing the Jammer classes if one wants to modify attributes of WirelessModuleUtility before simulation starts.

Jammers are turned off by default when simulation starts, one should schedule an event to start the jammer after simulation starts.

 /* obtain pointer to jammer from jammer container */
 Ptr<Jammer> jammerPtr = jammers.Get (0);
 /* schedule jammer to start at 7.0 seconds */
 Simulator::Schedule (Seconds (7.0), &ns3::Jammer::StartJammer, jammerPtr);

Jamming Mitigation

The following code snippet installs a jamming mitigation object (mitigate by channel hop) onto a node with modified wifi PHY (NslWifiPhy) already installed.

 /* create some nodes */ 
 NodeContainer c;
 c.Create(5);
 
 /* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */
 
 /* install jamming mitigation objects */
 JammingMitigationHelper mitigationHelper;
 // configure mitigation type
 mitigationHelper.SetJammingMitigationType ("ns3::MitigateByChannelHop");
 // configure mitigation parameters
 mitigationHelper.Set ("MitigateByChannelHopChannelHopDelay",
                       TimeValue (Seconds (0.0)));
 mitigationHelper.Set ("MitigateByChannelHopDetectionMethod",
                       UintegerValue (MitigateByChannelHop::PDR_AND_RSS));
 // install mitigation on honest nodes
 JammingMitigationContainer mitigators = mitigationHelper.Install (honestNodes);
 // get pointer to mitigation object from jamming mitigation container
 Ptr<JammingMitigation> mitigationPtr = mitigators.Get (0);

Wireless Module Utility

The following code snippet installs a wireless module utility object onto a node with modified wifi PHY (NslWifiPhy) object already installed.

 /* create some nodes */ 
 NodeContainer c;
 c.Create(5);
 
 /* use NslWifiPhyHelper to install NslWifiPhy. Similar to installing the regular YansWifiPhy */
 
 /* install WirelessModuleUtility */
 WirelessModuleUtilityHelper utilityHelper;
 // set inclusion/exclusion list for all nodes
 std::vector<std::string> AllInclusionList;
 AllInclusionList.push_back ("ns3::UdpHeader");          // record only UdpHeader
 std::vector<std::string> AllExclusionList;
 AllExclusionList.push_back ("ns3::olsr::PacketHeader"); // ignore all olsr headers/trailers
 // assign lists to helper
 utilityHelper.SetInclusionList (AllInclusionList);
 utilityHelper.SetExclusionList (AllExclusionList);
 // install on all nodes
 WirelessModuleUtilityContainer utilities = utilityHelper.InstallAll ();