Difference between revisions of "Wireshark Plugin"

From OpenUru
Jump to: navigation, search
(Created page with 'Welcome to the main page for the Uru Wireshark plugin! = Do I care about this? = Wireshark is a GUI-based network protocol analysis tool. (There is a command-line version too.)…')
 
(Contributing)
Line 50: Line 50:
 
OpenURU.org has a JIRA installation. You may use it for [http://foundry.openuru.org:7080/browse/WIREPLUG bugs and patch contributions]. As of right now there is a limited number of JIRA accounts, so you can submit bugs "anonymously". Please include in the report a forum name or some other reasonable contact information!
 
OpenURU.org has a JIRA installation. You may use it for [http://foundry.openuru.org:7080/browse/WIREPLUG bugs and patch contributions]. As of right now there is a limited number of JIRA accounts, so you can submit bugs "anonymously". Please include in the report a forum name or some other reasonable contact information!
  
Code contributions will be code-reviewed for safety and correctness. There are currently no plans to reject anything based on content unless it is actually incorrect. If you want commit access, contribute a couple working patches and then ask for access. This protocol may change in the future if it does not work.
+
Code contributions will be code-reviewed for safety and correctness. Please keep code to 79 columns or fewer. There are currently no plans to reject anything based on content unless it is actually incorrect. If you want commit access, contribute a couple working patches and then ask for access. This protocol may change in the future if it does not work.

Revision as of 17:27, 31 May 2010

Welcome to the main page for the Uru Wireshark plugin!

Do I care about this?

Wireshark is a GUI-based network protocol analysis tool. (There is a command-line version too.) In short, it lets you look at network traffic to see what is going on, even in real-time. a'moaca' has figured out Uru bugs based on real-time behavior related to what is seen on the network, in addition to more subtle bugs discovered with detailed later analysis.

Generally this tool will only be of interest to those working on the protocol or client/server code. It is also interesting for a more hobbyist "figure out how it works" perspective.

But there is a caveat. The MOUL protocol (which the plugin calls "UruLive") is protected by a form of public-key encryption. This means that the Uru plugin cannot read the contents of any but the very first packets of each connection, unless you have the private key or some means of determining the negotiated session key.

Only Cyan should have the private key. Anyone writing new clients can choose to expose the session key for use with the Wireshark plugin. When people can run their own servers, they will in turn have their own private keys and they can use the plugin too. If you wish to use the plugin otherwise, I leave you to your creativity.

The plugin will work on old UU/Alcugs traffic, though, should you happen to have any to look at.

History (why are things this weird way?)

a'moaca' first started the plugin while debugging a linking hang with old Alcugs (unet2) code. The resulting bare-bones transport-layer only version of the plugin was checked into the Alcugs repository (where some Alcugs-specific code was later added that is not present in this version as of now). Later, in support of other projects, a'moaca' began adding dissection of the rest of the protocol, based almost entirely on the Alcugs server code itself. This is the reason many of the names in the plugin are what they are.

The hobbyist perspective led to gradually more dissection, proceeding on to the MOUL protocol. Over time, cjkelly1 has contributed a lot to the plugin as well, including some code contributions, effort spent figuring things out, testing, a lot of Windows-specific testing (usually unintentional but sometimes planned), and providing some of the correct names for things.

Very little of the knowledge added by a'moaca' and cjkelly1 after what originated from the Alcugs source came from disassembly, the "usual" method of Uru reverse-engineering. It was done by looking at real traffic and educated guessing. This is the reason many other names are what they are, and this is why there are still some gaps in the dissection.

If you want to fix any of this, submit a patch!

How to use it

(At the moment there isn't a compiled executable to distribute. This could change in the future. Until/unless a precompiled version is available, you will have to compile your own. For that, see the next section.)

Using the Uru plugin is not much different than using Wireshark for any other protocol. Here are some extra notes:

  • There are two configuration sections, "Uru" and "UruLive". The "Uru" section covers configuration specific to the Prologue/UU/PotS protocol. The "UruLive" section covers configuration specific to the MOUL/MOULa protocol. Anything common to both is also in the "Uru" section (this is the toggle for hiding fields, and all SDL-related configuration).
  • Be careful with your SDL files. Unfortunately, the MOUL SDL files are not a strict superset of PotS files (I believe there is at least one mismatch with the same version number, for example). Genrally one copy will suffice, though. If you do not provide SDL files, the plugin will use a crummy but serviceable algorithm that guesses the field types.
  • The UruLive configuration contains several choices for protocol versioning. These apply to MOUL versions. You can basically ignore them unless you have old uncrypted traces. The default (Live 9, autodetect) should be good.
  • Two ways to decrypt MOUL connections are provided: giving Wireshark each session key, or giving it the private key data for each type of connection.
    • The first way requires configuring the 7-byte session key, if you have a way to determine it. This key is negotiated each connection. The input box accepts a comma-separated list of port=key pairs. Use the client port number (the one that is not 14617); this is how the plugin associates each key with a connection. The 7 bytes of the key should be in hexadecimal. An example value might be:
1050=1A2B3C4D5E6F70,1053=1234ABCD5678EF
  • The second way requires knowledge of the server private key. Provide a key file for each connection type (auth, game, gatekeeper). The format of the key file is 128 bytes of binary data. The first 64 bytes are the modulus in big-endian order (note it is little-endian in the exectuables), and the second 64-bytes are the private key, again big-endian. (This key file choice is based on the baseless assumption that the actual key files are stored in a common format such as DER, which is big-endian.)

How to compile it

The code is present in OpenURU.org's Subversion repository at http://foundry.openuru.org/svn/wireshark_plugin. To check it out, use your favorite Subversion GUI with username "guest" and password "guest", or on the command line:

svn co --username guest --password guest http://foundry.openuru.org/svn/wireshark_plugin

This will check out the latest version of the source in the current directory. You will also need a copy of the Wireshark source. It may be downloaded from the Wireshark site. Using the "Development Release" is recommended, as the patch provided will work with that tree. Version 1.2.8 or newer will also work, but you will need to patch plugins\Makefile.nmake yourself, as the structure of the file differs between 1.2.x and the development trunk.

In the plugin directory, the INSTALL file provides build directions. The basic idea is that you patch the plugin into the Wireshark build and then build Wireshark normally. So you should be able to follow Wireshark's build documentation.

The Developer's Guide contains build instructions, which are pretty minimal. If you are building for Windows, check the additional instructions and a'moaca' uses this wiki page.

Contributing

OpenURU.org has a JIRA installation. You may use it for bugs and patch contributions. As of right now there is a limited number of JIRA accounts, so you can submit bugs "anonymously". Please include in the report a forum name or some other reasonable contact information!

Code contributions will be code-reviewed for safety and correctness. Please keep code to 79 columns or fewer. There are currently no plans to reject anything based on content unless it is actually incorrect. If you want commit access, contribute a couple working patches and then ask for access. This protocol may change in the future if it does not work.