From a1f08a07ee965cddf978214b6e1fedc7223b73f7 Mon Sep 17 00:00:00 2001 From: Sebastian Lohff Date: Mon, 16 Jan 2012 20:53:34 +0100 Subject: [PATCH] README for vRFC1149 --- tunnel/vrfc1149/README | 88 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 2 deletions(-) diff --git a/tunnel/vrfc1149/README b/tunnel/vrfc1149/README index cc16ea1..87d4017 100644 --- a/tunnel/vrfc1149/README +++ b/tunnel/vrfc1149/README @@ -1,7 +1,91 @@ +vRFC1149 +======== +This is an implementation of "IP over Avian Carrier", using tweets as +virtualized avian carrier. -Installation -============ +Installation and requirements +============================= You need * tweepy >= 1.8 (https://github.com/tweepy/tweepy.git) * python-bytearray + +Each client needs a twitter account to tweet network packets and one +account to follow for incoming network packets. If the tweets of each account +are public, the accounts don't need to follow each other. Currently, only point +to point connections are possible, as specified by RFC1149. + + +How it works +============ +The script needs one Twitter account. It registers the account via oAuth, so it +becomes accessible (see Authorization) and then pull tweets from it via Twitter's +streaming-API. Tweets are en-/decoded and (de-)fragmented using packaging +helper (see Encoding). Incoming tweets are parsed as incoming traffic, outgoing +traffic is fragmented, encoded and then tweeted. + + +Authorization +~~~~~~~~~~~~~ +The script needs to be associated with Twitter through oAuth. If it is started +without credentials, it gives you a link to twitter.com with a generated token +and then asks for a PIN. After entering the PIN the script is fully +authorized to both tweet and read tweets. The ACCESS_KEY and ACCESS_SECRET are +saved into conf_auth.py. + +If the script already has an ACCESS_KEY and ACCESS_SECRET you won't be asked +for credentials again. + + +Encoding +~~~~~~~~ +A tweet's maximum length is 140 characters. One character for twitter is one +unicode character, meaning that one character can encode 20 bits (current +uncode range is 0x0-0x110000). In vRFC1149's implementation two bytes are +encoded in each character, leaving 4 bit of each char for metadata (the +header). + +Sadly twitter removes, mangles or augmentates some of +the characters. For more information about this look into the comments in the +source (phelper.UPHelper.reassembleBrokenChars()). + +An alternative approach is to just tweet everything plain, reducing the payload +of a tweet to 138 bytes (2 bytes reserved for header). Nevertheless, twitter +transforms certain characters (<,> to <, >), so a workarround is needed, +too. + +All available packaging helpers can be found in phelper.py. + + +Twitter API Limits +~~~~~~~~~~~~~~~~~~ +Twitter allows each client to do 1000 tweets a day. When considering a +continuous connection and a tweet size of 280 bytes, the average speed is about +3byte/s (273kb/day). Additional, twitter breaks down the 1000 tweets to an +unspecified hourly limit. + + +RFC1149 compability +=================== +This implementation of RFC1149 does not reach 100% compability, since the +general tweet comes without a leg on which the message could be taped to. +Also, no duct tape is used (no taping whatsoever). + +Regarding the encoding, one could write a packaging helper more compatible +with the RFC's frame format (hexadecimal representation with seperated octets). +As a side effect, it would reduce the payload of one tweet to 46 bytes. + + +What could be done +================== + * create network topologies with Twitter's "following" feature + * support multiple clients + * create a table of characters which are not "eaten" by twitter or what they + get transformed to + + +Licensing +========= +Written by Sebastian Lohff +Published under the GPLv3 or later +