Wednesday, 7 May 2014

Microsoft Lync Wireshark Plugin

In this post I have the pleasure of talking about a project that I’ve been working on for a while, as well as one of my all-time favourite networking tools - Wireshark! For those that don’t know, Wireshark (originally named Ethereal) is a packet sniffer program that decodes hundreds of networking protocols for your viewing pleasure. I’ve been using Wireshark for about 10 years now, and am extremely appreciative of all of the people that have worked to build and maintain the product over the years. The other amazing thing about Wireshark is that it’s free software and works across all the major OS platforms. So if you haven’t used it before, I suggest you use this as an opportunity to download it and give it a try.

As an IT professional working on Lync, what can Wireshark do for you? Well, it can do quite a few things: I personally use it all the time for troubleshooting connection issues, networking problems, certificate negotiation, and other protocol issues. When I started using Wireshark with Lync I found that some protocols are not decoded properly by Wireshark, which made me sad. For example, STUN (Simple Traversal Utilities for NAT) is a protocol used extensively with Lync is only partially decoded by Wireshark. 

Example:


So why can’t Wireshark decode these STUN messages properly? The answer to this is that Microsoft has made additions to the base IETF standards which are not recognised by Wireshark. The good news is that Microsoft documented these extensions and released them to the world. Some examples of these documents can be found here:

Microsoft Protocol Documentation:      

These documents that are provided by Microsoft extend the base level standards that were originally written by the Internet Engineering Task Force (IETF). Here are some examples of these specifications:

IETF Protocol Documentation:


Lync Wireshark Plugin

Armed with the information available in the Microsoft’s Office Protocol documents, RFCs, and a healthy dose of reverse engineering, I was able to put together a plugin for Wireshark that made packet captures taken on an Edge server readable. Below is an example of a packet capture taken on an Edge server:


So without further ado, I give you The Lync Wireshark Plugin:

1.00 Initial Release:
  • This Wireshark plugin is designed to dissect Lync AV Edge and Internal Edge AV traffic. Captures can be taken on the Edge server (Capturing AV Edge External traffic, and Internal Interface traffic), or it can also be used on the client side for decoding STUN and RTP/RTCP traffic.
  • This Wireshark plugin dissects STUN/TURN traffic on Microsoft Lync Edge port 3478 (STUN, RTCP, RTP)
  • This Wireshark plugin dissects traffic on Microsoft Lync Edge port 443 (STUN, RTCP, RTP)
  • This Wireshark plugin dissects dynamically assigned RTP and RTCP traffic by using ports allocated in STUN requests.
  • Dissector can be turned on/off within Wireshark Preferences. (Edit->Preferences->Protocols->LYNC_DECODER)
  • Port numbers can be changed within Wireshark Preferences. (Edit->Preferences->Protocols->LYNC_DECODER)
  • If you enter “lync_decoder” in the Filter bar, only the traffic that is being decoded by the Lync Plugin will be displayed.
  • To be used with the latest release of Wireshark (however, the plugin should work with higher than Wireshark 1.0)




Note: The Lync Wireshark Plugin by default will take over the dissection of UDP port 3478 and TCP port 443. You can turn these off in the plugin settings found under Edit->Preferences…->Protocols->LYNC_DECODER.


Feedback

It’s a complex balancing act decoding multiple protocols that are multiplexed on the same port numbers. So there may be cases where you run into something I haven’t seen before that may cause an error in the decode. If you have an issue with the Plugin not decoding something correctly, or LUA errors with your captures, please email me (mylynclab <at> gmail <dot> com) an example of the capture (ie. a Wireshark pcap file) and tell me the packet number where you had the error. I will endeavour to maintain the plugin and correct issues that people might find. 

Known Issues:
  • Wireshark has a bug in the TFTP dissector that causes it to try and decode some STUN packets as TFTP, which results is a “[Malformed Packet: TFTP]” error. You will only see this if you have the Plugin setting “Show original Wireshark Dissection Tree” enabled. This is a Wireshark bug.
  • The plugin currently doesn't decode X-Address data for IPv6 packets. I don't have a capture of this to test on at the moment. If someone would like to supply one I can add the functionality. 


Installation of Plugin

Installing the plugin could not be simpler. You simply take the plugin file (LyncDissector.lua) and put it in the following directory:

"C:\Program Files\Wireshark\plugins\<wireshark version number>\"

After this, whenever you open Wireshark, this plugin will also be used to decode protocols.

Example:



Plugin Settings

The plugin has some variables that can be set to change what is getting decoded. The settings are accessed through Edit->Preferences…->Protocols->LYNC_DECODER. By default all decoding is enabled (ie. UDP port 3578, TCP port 443, and dynamically assigned RTP ports).



Plugin Settings:

Setting
Purpose
Decode UDP Port (Default 3478)
Port 3478 is the standard port used for STUN protocol on the Lync Edge and Lync Front End servers.
Decode TCP Internal Port (Default 443)
Port 443 is the standard port used by Internal Edge services. The Access Edge port gets sent STUN messaging on this port. Use this setting to enable or disable the plugin from decoding traffic on this port.

Note: Port 443 is usually used for HTTP TLS connections, so you may choose to turn off this plugin for port 443 to allow you to use the original Wireshark dissectors for decoding TLS traffic (ie. decoding certificate negotiations) on port 443.
Decode TCP External Port (Default 443)
Port 443 is the standard port used by Internal Edge services. This will always be 443, however, it’s a variable for if something changes in the future. Use this setting to enable or disable the plugin from decoding traffic on this port.

Note: Port 443 is usually used for HTTP TLS connections, so you may choose to turn off this plugin for port 443 to allow you to use the original Wireshark dissectors for decoding TLS traffic (ie. decoding certificate negotiations) on port 443.
Decode 1024-59999 Dynamic Ports
The 1024-50000 dynamic ports are the ports used by Servers and Clients for RTP connections. By turning this setting on, the Plugin will look in STUN messages for RTP ports that are being negotiated during session establishment and add these ports to the decode.
UDP Port (Default 3478)
This port in theory should always be 3478. However, if you would like to change this port number you can.
TCP Internal Port (Default 443)

The TCP decode ports have been broken into separate Internal and External settings. This is for when you are capturing on an Edge server that has a different port than 443 configured for the External AV edge. By default internal and external AV (TCP STUN, RTP, RTCP) traffic will be on port 443.   
TCP External AV Port (Default 443)
Show original Wireshark Dissection Tree (Default False)
When you are running the Lync Wireshark Plugin it will override the original Wireshark decode for the ports that have been selected above.

If you would like to also see how Wireshark would decode the packets, you can tick this box and the original default Wireshark decode will be displayed in the tree item above the plugin decode.

Warning: The default Wireshark dissectors break on some Lync STUN packets, displaying a TFTP decode error. So if you enable showing the original Wireshark dissector, some packets will not get decoded properly because of this error.

More Details on how Lync Edge protocols work

There was a great blog post written back in the 2010 about OCS that talks in some depth about how the STUN and TURN protocols are used by Lync. So if you would like more of an overview of the protocols have a read of this post.


Alternative Software

Microsoft also has their version of Wireshark that they call Network Monitor. They also have a Parser pack for Lync that will decode STUN and RTP messages. Here is where you can get Network Monitor and the Lync parser pack:


Note: Network Monitor does not decode TCP (443) STUN/RTP messages and limited STUN attributes.

The Wrap Up

In this post we have travelled to tech town via the Metro (which recently had it’s name changed to something that I can never seem to remember). The outlook from the windows of the train carriage were amazing, with vistas as far as the eye could see. When we passed through the gates of the city we were given the bill by the conductor which, as it turns out, was free for onedriveonly. The word around town was that there was a publisher that excelled at Lync projects. We tried to gain access to him and see if he would sharepoint his wisdom with us. After much looking, we finally found him and he cryptically told us that the infoPath to enlightenment was perhaps closer than we knew, and that we already had the powerpoint to realise this if we looked deep enough within ourselves. The trip allowed us to plug back in to our natural surroundings and be at onenote with nature. I hope you had as much fun as I did... Oh dear, it seems I have “Jumped the Wireshark” with the puns on this wrap up… J


Read more →

Popular Posts