From 07daef3320a2ceaa0c6a2c34eb98ece889789aed Mon Sep 17 00:00:00 2001
From: Daniel Roesler <diafygi@gmail.com>
Date: Sun, 25 Jan 2015 22:39:55 -0800
Subject: [PATCH] Updated README with description and code

---
 README.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 71 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 95957b8..e86e905 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,72 @@
-# webrtc-ips
+# STUN IP Address requests for WebRTC
+
 Demo: https://diafygi.github.io/webrtc-ips/
+
+### What this does
+
+Firefox and Chrome have implemented WebRTC that allow requests to STUN servers be made that will return the local and public IP addresses for the user. These request results are available to javascript, so you can now obtain a users local and public IP addresses in javascript. This demo is an example implementation of that.
+
+Additionally, these STUN requests are made outside of the normal XMLHttpRequest procedure, so they are not visible in the developer console or able to be blocked by plugins such as AdBlockPlus or Ghostery. This makes these types of requests available for online tracking if an advertiser sets up a STUN server with a wildcard domain.
+
+### Code
+
+Here is the annotated demo function that makes the STUN request. You can copy and paste this into the Firefox or Chrome developer console to run the test.
+
+```javascript
+//get the IP addresses associated with an account
+function getIPs(callback){
+    var ip_dups = {};
+
+    //compatibility for firefox and chrome
+    var RTCPeerConnection = window.RTCPeerConnection
+        || window.mozRTCPeerConnection
+        || window.webkitRTCPeerConnection;
+    var mediaConstraints = {
+        optional: [{RtpDataChannels: true}]
+    };
+
+    //firefox already has a default stun server in about:config
+    //    media.peerconnection.default_iceservers =
+    //    [{"url": "stun:stun.services.mozilla.com"}]
+    var servers = undefined;
+
+    //add same stun server for chrome
+    if(window.webkitRTCPeerConnection)
+        servers = {iceServers: [{urls: "stun:stun.services.mozilla.com"}]};
+
+    //construct a new RTCPeerConnection
+    var pc = new RTCPeerConnection(servers, mediaConstraints);
+
+    //listen for candidate events
+    pc.onicecandidate = function(ice){
+
+        //skip non-candidate events
+        if(ice.candidate){
+
+            //match just the IP address
+            var ip_regex = /([0-9]{1,3}(\.[0-9]{1,3}){3})/
+            var ip_addr = ip_regex.exec(ice.candidate.candidate)[1];
+
+            //remove duplicates
+            if(ip_dups[ip_addr] === undefined)
+                callback(ip_addr);
+
+            ip_dups[ip_addr] = true;
+        }
+    };
+
+    //create a bogus data channel
+    pc.createDataChannel("");
+
+    //create an offer sdp
+    pc.createOffer(function(result){
+
+        //trigger the stun server request
+        pc.setLocalDescription(result, function(){});
+
+    }, function(){});
+}
+
+//Test: Print the IP addresses into the console
+getIPs(function(ip){console.log(ip);});
+```