Content: Basic_Open_Bridge.html

File Basic_Open_Bridge.html, 11.4 KB (added by sponge, 9 years ago)
Line 
1<html><head>
2<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
3</head><body>
4<p>Since using I2P for a few years, and dealing with SAM and all it's
5problems I realized very quickly that something different was needed.
6This is what I came up with.</p>
7<p>Separate the commands from the data channels. To do this, Two things are needed:</p>
8<p>One, an application command channel socket to router.</p>
9<p>Two, the application data sockets to/from router that carry only data.</p>
10
11<p>The command channel is only needed for making or setting the initial
12destination key, and to set the destination key to port bindings. That
13is how SAM should have been done in the first place, but was not! :-)</p>
14
15<p>Note that YOUR application holds the keypair values, NOT the router. This is to reduce any extra complexity in the router code.</p>
16
17<p>KEYS = keypair public+private, these are BASE64</p>
18<p>KEY = public key, BASE64</p>
19
20<p>ERROR as is implied returns the message "ERROR "+DESCRIPTION+"\n", where the DESCRIPTION is what went wrong.</p>
21<p>OK returns "OK", and if data is to be returned, it is on the same line. OK means the command is finished.</p>
22<p>DATA lines contain information that you requested. There may be multiple DATA lines per request.</p>
23<p>NOTE: The help command is the ONLY command that has an exception to
24the rules... it can actually return nothing! This is intentional, since
25help is a HUMAN and not an APPLICATION command.
26</p><p>For CURRENT details on the commands PLEASE use the built-in
27help command. Here are the commands we have as of this writing (Dec
282008).
29</p><pre>
30COMMAND         OPERAND                                 RETURNS
31help            (optional command to get help on)       NOTHING or OK and description of the command
32clear                                                   ERROR or OK
33getdest                                                 ERROR or OK and KEY
34getkeys                                                 ERROR or OK and KEYS
35getnick         tunnelname                              ERROR or OK
36inhost          hostname or IP address                  ERROR or OK
37inport          port number                             ERROR or OK
38list                                                    ERROR or DATA lines and final OK
39newkeys                                                 ERROR or OK and KEY
40option                                                  ERROR or OK
41outhost         hostname or IP address                  ERROR or OK
42outport         port number                             ERROR or OK
43quiet                                                   ERROR or OK
44quit                                                    OK and terminates the command connection
45setkeys         KEYS                                    ERROR or OK
46setnick         tunnel nickname                         ERROR or OK
47show                                                    ERROR or OK and information
48start                                                   ERROR or OK
49status          tunnel nickname                         ERROR or OK and information
50stop                                                    ERROR or OK
51verify          KEY                                     ERROR or OK
52</pre><p>
53Once set up, all TCP sockets can and will block as needed, and there is no need for any
54additional messages to/from the command channel. This allows the router to pace the
55stream without exploding with OOM like SAM does as it chokes on attempting to shove
56many streams in or out one socket -- that can't scale when you have alot of connections!
57</p><p>
58What is also nice about this particular interface is that writing anything to interface
59to it, is much much easier than SAM. There is no other processing to do after the set up.
60It's configuration is so simple, that very simple tools, such as nc (netcat) can be used
61to point to some application. The value there is that one could schedule up and down times
62for an application, and not have to change the application to do that, or to even have
63to stop that application. Instead, you can litterally "unplug" the destination, and
64"plug it in" again. As long as the same IP/port addresses and destination keys are used
65when bringing the bridge up, the normal TCP application won't care, and won't notice.
66It will simply be fooled -- the destinations are not reachable, and that nothing is coming in.
67</p><p>
68For the following example, we'll setup a very simple local loopback connection,
69with two destinations. Destination "bitch" will be the CHARGEN service from
70the INET superserver daemon. Destination "ear" will be a local port that you
71can telnet into, and watch the pretty ASCII test puke forth.
72</p><pre>EXAMPLE SESSION DIALOGUE -- simple telnet 127.0.0.1 2827 works
73A = Application
74C = BOB's Command response.
75
76FROM    TO      DIALOGUE
77A       C       setnick bitch
78C       A       OK Nickname set to bitch
79A       C       newkeys
80C       A       OK ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ngnkSwGdUfM7hGccqBYDjIubTrlr~0g2-l0vM7Y8nSqtFrSdMw~pyufXZ0Ys3NqUSb8NuZXpiH2lCCkFG21QPRVfKBGwvvyDVU~hPVfBHuR8vkd5x0teMXGGmiTzdB96DuNRWayM0y8vkP-1KJiPFxKjOXULjuXhLmINIOYn39bQprq~dAtNALoBgd-waZedYgFLvwHDCc9Gui8Cpp41EihlYGNW0cu0vhNFUN79N4DEpO7AtJyrSu5ZjFTAGjLw~lOvhyO2NwQ4RiC4UCKSuM70Fz0BFKTJquIjUNkQ8pBPBYvJRRlRG9HjAcSqAMckC3pvKKlcTJJBAE8GqexV7rdCCIsnasJXle-6DoWrDkY1s1KNbEVH6i1iUEtmFr2IHTpPeFCyWfZ581CAFNRbbUs-MmnZu1tXAYF7I2-oXTH2hXoxCGAAAA
81</pre><p>
82MAKE NOTE OF THE ABOVE DESTINATION KEY, YOURS WILL BE DIFFERENT!
83</p><pre>
84FROM    TO      DIALOGUE
85A       C       outhost 127.0.0.1
86C       A       OK outhost set
87A       C       outport 19
88C       A       OK outbound port set
89A       C       start
90C       A       OK tunnel starting
91</pre><p>
92At this point, there was no error, a destination with a nickname of "bitch"
93is set up. When you contact the destination provided, you actually connect
94to the CHARGEN service on 19/TCP.
95</p><p>
96Now for the other half, so that we can actually contact this destination.
97</p><pre>
98FROM    TO      DIALOGUE
99A       C       setnick ear
100C       A       OK Nickname set to ear
101A       C       newkeys
102C       A       OK 8SlWuZ6QNKHPZ8KLUlExLwtglhizZ7TG19T7VwN25AbLPsoxW0fgLY8drcH0r8Klg~3eXtL-7S-qU-wdP-6VF~ulWCWtDMn5UaPDCZytdGPni9pK9l1Oudqd2lGhLA4DeQ0QRKU9Z1ESqejAIFZ9rjKdij8UQ4amuLEyoI0GYs2J~flAvF4wrbF-LfVpMdg~tjtns6fA~EAAM1C4AFGId9RTGot6wwmbVmKKFUbbSmqdHgE6x8-xtqjeU80osyzeN7Jr7S7XO1bivxEDnhIjvMvR9sVNC81f1CsVGzW8AVNX5msEudLEggpbcjynoi-968tDLdvb-CtablzwkWBOhSwhHIXbbDEm0Zlw17qKZw4rzpsJzQg5zbGmGoPgrSD80FyMdTCG0-f~dzoRCapAGDDTTnvjXuLrZ-vN-orT~HIVYoHV7An6t6whgiSXNqeEFq9j52G95MhYIfXQ79pO9mcJtV3sfea6aGkMzqmCP3aikwf4G3y0RVbcPcNMQetDAAAA
103A       C       inhost 127.0.0.1
104C       A       OK inhost set
105A       C       inport 37337
106C       A       OK inbound port set
107A       C       start
108C       A       OK tunnel starting
109A       C       quit
110C       A       OK Bye!
111
112</pre><p>
113Now all we need to do is telnet into 127.0.0.1, port 37337,
114send the destination key or host address from addressbook we want to contact.
115In this case, we want to contact "bitch", all we do is paste in the
116key and it goes.
117</p><p>
118NOTE: The "quit" command in the command channel does NOT disconnect the tunnels like SAM.
119</p><pre>
120# telnet 127.0.0.1 37337
121Trying 127.0.0.1...
122Connected to 127.0.0.1.
123Escape character is '^]'.
124ZMPz1zinTdy3~zGD~f3g9aikZTipujEvvXOEyYfq4Su-mNKerqG710hFbkR6P-xkouVyNQsqWLI8c6ngnkSwGdUfM7hGccqBYDjIubTrlr~0g2-l0vM7Y8nSqtFrSdMw~pyufXZ0Ys3NqUSb8NuZXpiH2lCCkFG21QPRVfKBGwvvyDVU~hPVfBHuR8vkd5x0teMXGGmiTzdB96DuNRWayM0y8vkP-1KJiPFxKjOXULjuXhLmINIOYn39bQprq~dAtNALoBgd-waZedYgFLvwHDCc9Gui8Cpp41EihlYGNW0cu0vhNFUN79N4DEpO7AtJyrSu5ZjFTAGjLw~lOvhyO2NwQ4RiC4UCKSuM70Fz0BFKTJquIjUNkQ8pBPBYvJRRlRG9HjAcSqAMckC3pvKKlcTJJBAE8GqexV7rdCCIsnasJXle-6DoWrDkY1s1KNbEVH6i1iUEtmFr2IHTpPeFCyWfZ581CAFNRbbUs-MmnZu1tXAYF7I2-oXTH2hXoxCGAAAA
125 !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefg
126!"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefgh
127"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghi
128#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghij
129$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijk
130...
131After a few virtual miles of this spew, press Control-]
132...
133cdefghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJK
134defghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=&gt;?@ABCDEFGHIJKL
135efghijklmnopqrstuvwxyz{|}~ !"#$%&amp;'()*+,-./0123456789:;&lt;=
136telnet&gt; c
137Connection closed.
138
139
140
141Here is what happened...
142telnet -&gt; ear -&gt; i2p -&gt; bitch -&gt; chargen -.
143telnet &lt;- ear &lt;- i2p &lt;- bitch &lt;-----------'
144
145</pre><p>
146You can connect to EEPSITES too!
147</p><pre>
148# telnet 127.0.0.1 37337
149Trying 127.0.0.1...
150Connected to 127.0.0.1.
151Escape character is '^]'.
152i2host.i2p
153GET / HTTP/1.1
154
155HTTP/1.1 200 OK
156Date: Fri, 05 Dec 2008 14:20:28 GMT
157Connection: close
158Content-Type: text/html
159Content-Length: 3946
160Last-Modified: Fri, 05 Dec 2008 10:33:36 GMT
161Accept-Ranges: bytes
162
163&lt;html&gt;
164&lt;head&gt;
165  &lt;title&gt;I2HOST&lt;/title&gt;
166  &lt;link rel="shortcut icon" href="favicon.ico"&gt;
167&lt;/head&gt;
168...
169&lt;a href="http://sponge.i2p/"&gt;--Sponge.&lt;/a&gt;&lt;/pre&gt;
170&lt;img src="/counter.gif" alt="!@^7A76Z!#(*&amp;amp;%"&gt; visitors. &lt;/body&gt;
171&lt;/html&gt;
172Connection closed by foreign host.
173#
174</pre><p>
175Pretty cool isn't it? Try some other well known EEPSITES if you like, nonexistant ones,
176etc, to get a feel for what kind of output to expect in different situations.
177For the most part, I suggest that you ignore any of the error messages.
178They would be meaningless to the application, and are only presented for human debugging.
179</p><p>
180Let's put down our destinations now that we are all done with them.
181</p><p>
182First, lets see what destination nicknames we have.
183</p><pre>
184FROM    TO      DIALOGUE
185A       C       list
186C       A       DATA NICKNAME: bitch STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: not_set INHOST: localhost OUTPORT: 19 OUTHOST: 127.0.0.1
187C       A       DATA NICKNAME: ear STARTING: false RUNNING: true STOPPING: false KEYS: true QUIET: false INPORT: 37337 INHOST: 127.0.0.1 OUTPORT: not_set OUTHOST: localhost
188C       A       OK Listing done
189
190</pre><p>
191Allright, there they are. First, let's remove "bitch".
192</p><pre>
193FROM    TO      DIALOGUE
194A       C       getnick bitch
195C       A       OK Nickname set to bitch
196A       C       stop
197C       A       OK tunnel stopping
198A       C       clear
199C       A       OK cleared
200
201</pre><p>
202Now to remove "ear", note that this is what happens when you type too fast,
203and shows you what typical ERROR messages looks like.
204</p><pre>
205FROM    TO      DIALOGUE
206A       C       getnick ear
207C       A       OK Nickname set to ear
208A       C       stop
209C       A       OK tunnel stopping
210A       C       clear
211C       A       ERROR tunnel is active
212A       C       clear
213C       A       OK cleared
214A       C       quit
215C       A       OK Bye!
216
217</pre>
218
219<p>I won't bother to show an example of the receiver end of a bridge
220because it is very simple. There are two possible settings for it, and
221it is toggled with the "quiet" command.
222</p><p>The default is NOT quiet, and the first data to come into your
223listening socket is the destination that is making the contact. It is a
224single line consisting of the BASE64 address followed by a newline.
225Everything after that is for the application to actually consume.
226</p><p>In quiet mode, think of it as a regular internet connection. No
227extra data comes in at all. It's just as if you are plain connected to
228the regular internet. This mode allows a form of transparency much like
229is available on the router console tunnel settings pages, so that you
230can use BOB to point a destination at a web server, for example, and
231you would not have to modify the web server at all.
232</p><p>The advantage with using BOB for this is as discussed
233previously. You could schedule random uptimes, etc for the application,
234redirect to a different machine, etc. One use of this may be something
235like wanting to try to goof up router-to-destination upness guessing.
236You could stop and start the destination with a totally different
237process to make random up and down times on services. That way you
238would only be stopping the ability to contact such a service, and not
239have to bother shutting it down and restarting it. You could redirect
240and point to a different machine on your lan while you do updates, or
241point to a set of backup machines depending on what is running, etc,
242etc. Only your imagination limits what you could do.
243</p><p>
244I realize that this really isn't looking like a full blown "API spec", however it's so simple
245that this is really, honestly, the entire API. The "PROTOCOL" is quite tiny, and there are only Three
246possible replies to the commands.
247</p>
248</body></html>