Initial commit
Change-Id: I6a4444e3c193dae437cd7929f4c39aba7b749efa
diff --git a/contrib/wireshark/HOWTO b/contrib/wireshark/HOWTO
new file mode 100644
index 0000000..d6d9123
--- /dev/null
+++ b/contrib/wireshark/HOWTO
@@ -0,0 +1,68 @@
+ --------
+ FOREWORD
+ --------
+
+The patch in this folder allows Wireshark to process packets that contain TLS-protected
+Diameter messages over SCTP multi-stream associations. Each SCTP stream pairs is handled
+as a separate TLS channel (RFC3436), which is consistent with freeDiameter 1.0.x mechanism.
+
+It should be noted however that rfc3588bis (revised Diameter) recommends that DTLS is used
+instead of TLS over SCTP, for the reasons highlighted in the introduction of RFC6083.
+When this new mechanism is implemented in freeDiameter, a different patch will probably
+be required for wireshark.
+
+
+The instructions in this file will change your wireshark binary in a way suitable for
+analysis of Diameter over TLS over SCTP, but may have unexpected side-effects
+on some other protocols analysis (including DTLS).
+
+The instructions refer to Debian-style packaging (apt), you should adapt
+the process to build a new modified package of wireshark for your distribution.
+
+The provided patch has been successfully tested with:
+ - wireshark-1.2.7 (Ubuntu Lucid)
+ - wireshark-1.2.11 (Ubuntu Maverick)
+It may or may not work on more recent or ancient versions.
+
+
+ ------------
+ INSTRUCTIONS
+ ------------
+
+The steps are:
+ - get your wireshark source
+ apt-get source wireshark
+ cd wireshark-1.2.*
+
+ - apply the patch
+ cat ~/wireshark-1.2.7-diameter-tls.patch | patch -p1
+
+ - increase the version number
+ dch -lfD "Added support for Diameter over TLS over SCTP"
+
+ - Create a new package, this might take a while
+ fakeroot debian/rules binary
+
+ - Install the modified version
+ sudo dpkg --install ../wireshark-common_*fD*.deb ../wireshark_*fD*.deb
+
+ - Start the new wireshark:
+ wireshark &
+
+To analyze a capture file, you will need the private keys of both peers involved.
+
+Let's imagine for example:
+ peer A with IP address 192.168.0.10 has private key privA.pem
+ peer B with IP address 192.168.0.11 has private key privB.pem
+
+In wireshark you must do the following:
+ - go to menu Edit->Preferences
+ - In the left panel, under Protocols, scroll to "SSL" and select it.
+ - In the right panel, fill "RSA keys list" as follow:
+ 192.168.0.10,3869,diameter,/absolute/path/to/privA.pem;192.168.0.11,3869,diameter,/absolute/path/to/privB.pem
+ - You may find also useful to select an SSL debug file to get a hint of any problem.
+
+Once this configuration is complete, you should be able to see the contents of SCTP packets,
+including protected Diameter payload.
+
+Check the "sample" subdirectory for a test capture file.