-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3952 4b5297f7-1745-476d-ba37-a9c6900126ab
- Loading branch information
Peter Saint-Andre
committed
Feb 22, 2010
1 parent
d98c56e
commit 87c01b6
Showing
1 changed file
with
124 additions
and
123 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,4 +1,5 @@ | ||
| <?xml version='1.0' encoding='UTF-8'?> | ||
| <![CDATA[ | ||
| <!DOCTYPE xep SYSTEM 'xep.dtd' [ | ||
| <!ENTITY % ents SYSTEM 'xep.ent'> | ||
| %ents; | ||
|
|
@@ -84,20 +85,20 @@ | |
| </section1> | ||
| <section1 topic='Registration/Setup'> | ||
| <p>The first step is to communicate with a PASS service to set it up.</p> | ||
| <example caption='Registration request'> | ||
| <iq id='pass1' type='set' to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <expire>600</expire> | ||
| </query> | ||
| </iq> | ||
| </example> | ||
| <example caption='Result from PASS Service'> | ||
| <iq id='pass1' type='result' from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <server port='43253'>1.2.3.4</server> | ||
| </query> | ||
| </iq> | ||
| </example> | ||
| <example caption='Registration request'><![CDATA[ | ||
| <iq id='pass1' type='set' to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <expire>600</expire> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <example caption='Result from PASS Service'><![CDATA[ | ||
| <iq id='pass1' type='result' from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <server port='43253'>1.2.3.4</server> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <p>At this point, the PASS service is now listening on the given IP and port for incoming connections on behalf of the Jabber Entity. The provided IP and port can now be sent to any other entity as a connection point, for file transfers or any other use.</p> | ||
| <p>The default behavior for the PASS service is to listen on the port forever, unless the requesting client specifies an <expire/> value (in seconds). If the service is not configured with an expire value, it will not timeout the connection, and will start listening on the port again after one of the two sides disconnects.</p> | ||
| <table caption='Error Codes'> | ||
|
|
@@ -115,97 +116,97 @@ | |
| </section1> | ||
| <section1 topic='Incoming Connections'> | ||
| <p>When an incoming connection is attempted to that IP and port, the PASS service MUST send an IQ request to the entity on whose behalf it is listening:</p> | ||
| <example caption='Request to entity'> | ||
| <iq type='set' | ||
| <example caption='Request to entity'><![CDATA[ | ||
| <iq type='set' | ||
| id='pass2' | ||
| to='[email protected]/resource' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client port='1234'>4.3.2.1</client> | ||
| <proxy port='43523'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| </example> | ||
| <example caption='IQ result to accept connection'> | ||
| <iq type='result' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client port='1234'>4.3.2.1</client> | ||
| <proxy port='43523'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <example caption='IQ result to accept connection'><![CDATA[ | ||
| <iq type='result' | ||
| id='pass2' | ||
| from='[email protected]/resource' | ||
| to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| </example> | ||
| to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| ]]></example> | ||
| <p>The entity SHOULD now immediately connect to the given proxy IP and port, and upon connection all data written to that socket will be copied to the client connection, and vice-versa. Any disconnect on either side MUST cause a disconnect on the other (initiated by the service). If the IQ set to the entity fails or returns an error, the client socket MUST be dropped as well. The client XML element provides the information about the remote end of the incoming socket.</p> | ||
| <p>Abuse in bandwidth or resources could become an issue, so PASS implementations SHOULD include strict and detailed rate and usage limits, allowing only limited usage by single entities and rate-limiting bandwidth used if necessary for both single connections or overall usage. These limits are implementation-specific.</p> | ||
| </section1> | ||
| <section1 topic='Controls'> | ||
| <p>A Jabber client can send various controls to the PASS service via the set to control how the PASS service behaves, how the server handles a listening port.</p> | ||
| <section2 topic='<expire/>'> | ||
| <p>This tells the server to shut down the port after a specified number of seconds. After the timeout period, the PASS service MUST send an <iq/> to the JID to tell it that the port has been closed down. It notifies the client with:</p> | ||
| <example caption='Notification of expiration'> | ||
| <iq type='set' | ||
| <section2 topic='<expire/>'> | ||
| <p>This tells the server to shut down the port after a specified number of seconds. After the timeout period, the PASS service MUST send an <iq/> to the JID to tell it that the port has been closed down. It notifies the client with:</p> | ||
| <example caption='Notification of expiration'><![CDATA[ | ||
| <iq type='set' | ||
| id='pass3' | ||
| to='[email protected]/resource' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <expire/> | ||
| <close/> | ||
| <proxy port='43253'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| </example> | ||
| <example caption='Acknowledgement of expiration'> | ||
| <iq type='result' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <expire/> | ||
| <close/> | ||
| <proxy port='43253'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <example caption='Acknowledgement of expiration'><![CDATA[ | ||
| <iq type='result' | ||
| id='pass3' | ||
| from='[email protected]/resource' | ||
| to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| </example> | ||
| to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| ]]></example> | ||
| </section2> | ||
| <section2 topic='<oneshot/>'> | ||
| <p>This tells the server to listen once, and then close the port. Even if the <expire/> has not been met, the <oneshot/> overrides that and shuts down the listening port. When this happens the server notifies the client with the following packet:</p> | ||
| <example caption='Server notifies client of oneshot port closing'> | ||
| <iq type='set' | ||
| <section2 topic='<oneshot/>'> | ||
| <p>This tells the server to listen once, and then close the port. Even if the <expire/> has not been met, the <oneshot/> overrides that and shuts down the listening port. When this happens the server notifies the client with the following packet:</p> | ||
| <example caption='Server notifies client of oneshot port closing'><![CDATA[ | ||
| <iq type='set' | ||
| id='pass4' | ||
| to='[email protected]/resource' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <oneshot/> | ||
| <close/> | ||
| <proxy port='43253'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| </example> | ||
| <example caption='Client acknowledges closing of oneshot port'> | ||
| <iq type='result' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <oneshot/> | ||
| <close/> | ||
| <proxy port='43253'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <example caption='Client acknowledges closing of oneshot port'><![CDATA[ | ||
| <iq type='result' | ||
| id='pass4' | ||
| from='[email protected]/resource' | ||
| to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| </example> | ||
| to='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| ]]></example> | ||
| </section2> | ||
| <section2 topic='<close/>'> | ||
| <section2 topic='<close/>'> | ||
| <p>This tells the server to explicitly shut down a listening port. Useful for when the client shuts down and can tell the PASS service to recycle the port. The server sends back:</p> | ||
| <example caption='Client request to shut down port'> | ||
| <iq type='set' | ||
| <example caption='Client request to shut down port'><![CDATA[ | ||
| <iq type='set' | ||
| id='pass5' | ||
| to='pass.jabber.org' | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <close/> | ||
| <proxy port='43253'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| </example> | ||
| <example caption='Server acknowledges port closing request'> | ||
| <iq type='result' | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <close/> | ||
| <proxy port='43253'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <example caption='Server acknowledges port closing request'><![CDATA[ | ||
| <iq type='result' | ||
| id='pass5' | ||
| to='[email protected]/resource' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| </example> | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| ]]></example> | ||
| <table caption='Error Codes'> | ||
| <tr> | ||
| <th>Code</th> | ||
|
|
@@ -214,8 +215,8 @@ | |
| </tr> | ||
| <tr> | ||
| <td>400</td> | ||
| <td>Missing <proxy/> specification.</td> | ||
| <td>Sent a <close/> w/o a <proxy/></td> | ||
| <td>Missing <proxy/> specification.</td> | ||
| <td>Sent a <close/> w/o a <proxy/></td> | ||
| </tr> | ||
| <tr> | ||
| <td>401</td> | ||
|
|
@@ -225,12 +226,12 @@ | |
| <tr> | ||
| <td>404</td> | ||
| <td>Port not found in registry.</td> | ||
| <td>The <proxy port=''/> was not a defined port.</td> | ||
| <td>The <proxy port=''/> was not a defined port.</td> | ||
| </tr> | ||
| <tr> | ||
| <td>405</td> | ||
| <td>Proxy IP does not match.</td> | ||
| <td>The IP sent in the <proxy/> does not match the IP of the pass-service</td> | ||
| <td>The IP sent in the <proxy/> does not match the IP of the pass-service</td> | ||
| </tr> | ||
| </table> | ||
| </section2> | ||
|
|
@@ -239,56 +240,56 @@ | |
| <section2 topic='Client Authentication'> | ||
| <p>The PASS protocol can be used for clients to talk to each other and find out information about each other. When a client wants to send a file to another client, it can use the jabber:iq:pass namespace to query the IP address of the other client. For example:</p> | ||
| <p>You send the other client:</p> | ||
| <example> | ||
| <iq type='get' | ||
| <example><![CDATA[ | ||
| <iq type='get' | ||
| id='pass6' | ||
| to='[email protected]/resource' | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| </example> | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'/> | ||
| </iq> | ||
| ]]></example> | ||
| <p>The other client SHOULD send back:</p> | ||
| <example> | ||
| <iq type='result' | ||
| <example><![CDATA[ | ||
| <iq type='result' | ||
| id='pass6' | ||
| to='[email protected]/resource' | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client>4.3.2.1</client> | ||
| <query> | ||
| </iq> | ||
| </example> | ||
| <p>Obviously the port is not going to be known, but the IP address will let you authenticate the JID via the PASS service since the PASS service tells you the <client/> information upon a connection.</p> | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client>4.3.2.1</client> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <p>Obviously the port is not going to be known, but the IP address will let you authenticate the JID via the PASS service since the PASS service tells you the <client/> information upon a connection.</p> | ||
| </section2> | ||
| <section2 topic='Denying a Connection'> | ||
| <p>When a server gets an Incoming Connection notification the client has the right to deny that connection based on the <client/> information that it receives. It can return an error to the PASS service specifying the <proxy/> port and hangup on the active <client/> connection and start listening again. This does not affect the <oneshot/> control. For example:</p> | ||
| <p>When a server gets an Incoming Connection notification the client has the right to deny that connection based on the <client/> information that it receives. It can return an error to the PASS service specifying the <proxy/> port and hangup on the active <client/> connection and start listening again. This does not affect the <oneshot/> control. For example:</p> | ||
| <p>The PASS service sends you:</p> | ||
| <example> | ||
| <iq type='set' | ||
| <example><![CDATA[ | ||
| <iq type='set' | ||
| id='pass7' | ||
| to='[email protected]/resource' | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client port='1234'>4.3.2.1</client> | ||
| <proxy port='43523'>1.2.3.4</proxy> | ||
| <query> | ||
| </iq> | ||
| </example> | ||
| from='pass.jabber.org'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client port='1234'>4.3.2.1</client> | ||
| <proxy port='43523'>1.2.3.4</proxy> | ||
| </query> | ||
| </iq> | ||
| ]]></example> | ||
| <p>Your client would send back:</p> | ||
| <example> | ||
| <iq type='error' | ||
| <example><![CDATA[ | ||
| <iq type='error' | ||
| id='pass7' | ||
| to='pass.jabber.org' | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client port='1234'>4.3.2.1</client> | ||
| <proxy port='43523'>1.2.3.4</proxy> | ||
| <query> | ||
| <error code='401' type='auth'> | ||
| <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> | ||
| </error> | ||
| </iq> | ||
| </example> | ||
| from='[email protected]/resource'> | ||
| <query xmlns='jabber:iq:pass'> | ||
| <client port='1234'>4.3.2.1</client> | ||
| <proxy port='43523'>1.2.3.4</proxy> | ||
| </query> | ||
| <error code='401' type='auth'> | ||
| <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/> | ||
| </error> | ||
| </iq> | ||
| ]]></example> | ||
| <table caption='Error Codes'> | ||
| <tr> | ||
| <th>Code</th> | ||
|
|
@@ -298,7 +299,7 @@ | |
| <tr> | ||
| <td>401</td> | ||
| <td>Unauthorized</td> | ||
| <td>The incoming <client/> does not match the <client/> from the client you want to exchange data with.</td> | ||
| <td>The incoming <client/> does not match the <client/> from the client you want to exchange data with.</td> | ||
| </tr> | ||
| </table> | ||
| </section2> | ||
|
|
||