XEP-0003: Proxy Accept Socket Service (PASS)

Abstract:This document defines a method for relaying media via proxies on the Jabber/XMPP network.
Authors:Jeremie Miller, Ryan Eatmon
Copyright:© 1999 - 2009 XMPP Standards Foundation. SEE LEGAL NOTICES.
Status:Deprecated
Type:Historical
Version:1.3
Last Updated:2007-01-17

WARNING: This document has been deprecated by the XMPP Standards Foundation. Implementation of the protocol described herein is not recommended. Developers desiring similar functionality should implement the protocol that supersedes this one (if any).

Table of Contents


1. Introduction
2. Registration/Setup
3. Incoming Connections
4. Controls
    4.1. <expire/>
    4.2. <oneshot/>
    4.3. <close/>
5. Security Considerations
    5.1. Client Authentication
    5.2. Denying a Connection
6. IANA Considerations
7. XMPP Registrar Considerations
8. XML Schema

Appendices
    A: Document Information
    B: Author Information
    C: Legal Notices
    D: Relation to XMPP
    E: Discussion Venue
    F: Requirements Conformance
    G: Notes
    H: Revision History

1. Introduction

Complete direct client-to-client file transfers presents a major problem for clients that are behind a firewall or NAT. Proxy Accept Socket Service (PASS) enables clients to do real-time file transfers via a third party; in addition, it does not limit clients to file transfers but enables any two clients to create a raw TCP socket between them for any purpose, such as VoIP (SIP/RTP), BEEP, or binary game data.

2. Registration/Setup

The first step is to communicate with a PASS service to set it up.

Example 1. Registration request

<iq id='pass1' type='set' to='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'>
    <expire>600</expire>
  </query>
</iq>

Example 2. 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>

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.

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.

Table 1: Error Codes

Code Message Cause
502 No more ports available. Try again later. The PASS service is listening on all of its available ports.

3. Incoming Connections

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:

Example 3. Request to entity

<iq type='set'
    id='pass2'
    to='user@jabber.org/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 4. IQ result to accept connection

<iq type='result'
    id='pass2'
    from='user@jabber.org/resource'
    to='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'/>
</iq>

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.

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.

4. Controls

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.

4.1 <expire/>

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:

Example 5. Notification of expiration

<iq type='set'
    id='pass3'
    to='user@jabber.org/resource'
    from='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'>
    <expire/>
    <close/>
    <proxy port='43253'>1.2.3.4</proxy>
  </query>
</iq>

Example 6. Acknowledgement of expiration

<iq type='result'
    id='pass3'
    from='user@jabber.org/resource'
    to='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'/>
</iq>

4.2 <oneshot/>

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:

Example 7. Server notifies client of oneshot port closing

<iq type='set'
    id='pass4'
    to='user@jabber.org/resource'
    from='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'>
    <oneshot/>
    <close/>
    <proxy port='43253'>1.2.3.4</proxy>
  </query>
</iq>

Example 8. Client acknowledges closing of oneshot port

<iq type='result'
    id='pass4'
    from='user@jabber.org/resource'
    to='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'/>
</iq>

4.3 <close/>

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:

Example 9. Client request to shut down port

<iq type='set'
    id='pass5'
    to='pass.jabber.org'
    from='user@jabber.org/resource'>
  <query xmlns='jabber:iq:pass'>
    <close/>
    <proxy port='43253'>1.2.3.4</proxy>
  </query>
</iq>

Example 10. Server acknowledges port closing request

<iq type='result'
    id='pass5'
    to='user@jabber.org/resource'
    from='pass.jabber.org'>
  <query xmlns='jabber:iq:pass'/>
</iq>

Table 2: Error Codes

Code Message Cause
400 Missing <proxy/> specification. Sent a <close/> w/o a <proxy/>
401 Port not registered to your JID. You did not register this port with the server.
404 Port not found in registry. The <proxy port=''/> was not a defined port.
405 Proxy IP does not match. The IP sent in the <proxy/> does not match the IP of the pass-service

5. Security Considerations

5.1 Client Authentication

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:

You send the other client:

Example 11. 

<iq type='get'
    id='pass6'
    to='them@jabber.org/resource'
    from='you@jabber.org/resource'>
  <query xmlns='jabber:iq:pass'/>
</iq>

The other client SHOULD send back:

Example 12. 

<iq type='result'
    id='pass6'
    to='you@jabber.org/resource'
    from='them@jabber.org/resource'>
  <query xmlns='jabber:iq:pass'>
    <client>4.3.2.1</client>
  <query>
</iq>

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.

5.2 Denying a Connection

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:

The PASS service sends you:

Example 13. 

<iq type='set'
    id='pass7'
    to='user@jabber.org/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>

Your client would send back:

Example 14. 

<iq type='error'
    id='pass7'
    to='pass.jabber.org'
    from='user@jabber.org/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>

Table 3: Error Codes

Code Message Cause
401 Unauthorized The incoming <client/> does not match the <client/> from the client you want to exchange data with.

6. IANA Considerations

This document requires no interaction with the Internet Assigned Numbers Authority (IANA) [1].

7. XMPP Registrar Considerations

No action on the part of the XMPP Registrar [2] is necessary as a result of this document, since 'jabber:iq:pass' is already a registered protocol namespace.

8. XML Schema

<?xml version='1.0' encoding='UTF-8'?>

<xs:schema
    xmlns:xs='http://www.w3.org/2001/XMLSchema'
    targetNamespace='jabber:iq:pass'
    xmlns='jabber:iq:pass'
    elementFormDefault='qualified'>

  <xs:annotation>
    <xs:documentation>
      The protocol documented by this schema is defined in
      XEP-0003: http://www.xmpp.org/extensions/xep-0003.html
    </xs:documentation>
  </xs:annotation>

  <xs:element name='query'>
    <xs:complexType>
      <xs:choice minOccurs='0' maxOccurs='unbounded'>
        <xs:element name='client' type='PassEntity'/>
        <xs:element name='close' type='empty'/>
        <xs:element name='expire' type='xs:unsignedLong'/>
        <xs:element name='oneshot' type='empty'/>
        <xs:element name='proxy' type='PassEntity'/>
        <xs:element name='server' type='PassEntity'/>
      </xs:choice>
    </xs:complexType>
  </xs:element>

  <xs:complexType name='PassEntity'>
    <xs:simpleContent>
      <xs:extension base='xs:NMTOKEN'>
        <xs:attribute name='port' type='xs:short' use='optional'/>
      </xs:extension>
    </xs:simpleContent>
  </xs:complexType>

  <xs:simpleType name='empty'>
    <xs:restriction base='xs:string'>
      <xs:enumeration value=''/>
    </xs:restriction>
  </xs:simpleType>

</xs:schema>

Appendices

Appendix A: Document Information

Series: XEP
Number: 0003
Publisher: XMPP Standards Foundation
Status: Deprecated
Type: Historical
Version: 1.3
Last Updated: 2007-01-17
Approving Body: XMPP Council
Dependencies: XMPP Core
Supersedes: None
Superseded By: None
Short Name: pass
Schema: <http://www.xmpp.org/schemas/pass.xsd>
Source Control: HTML  RSS

Appendix B: Author Information

Jeremie Miller

Email: jer@jabber.org
JabberID: jer@jabber.org

Ryan Eatmon

Email: reatmon@jabber.org
JabberID: reatmon@jabber.org

Appendix C: Legal Notices

Copyright

This XMPP Extension Protocol is copyright © 1999 - 2009 by the XMPP Standards Foundation (XSF).

Permissions

Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.

Disclaimer of Warranty

## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. In no event shall the XMPP Standards Foundation or the authors of this Specification be liable for any claim, damages, or other liability, whether in an action of contract, tort, or otherwise, arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification. ##

Limitation of Liability

In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising out of the use or inability to use the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.

IPR Conformance

This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which may be found at <http://xmpp.org/extensions/ipr-policy.shtml> or obtained by writing to XSF, P.O. Box 1641, Denver, CO 80201 USA).

Appendix D: Relation to XMPP

The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.

Appendix E: Discussion Venue

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <http://xmpp.org/about/discuss.shtml> for a complete list.

Errata may be sent to <editor@xmpp.org>.

Appendix F: Requirements Conformance

The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

Appendix G: Notes

1. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.

2. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <http://xmpp.org/registrar/>.

Appendix H: Revision History

Version 1.3 (2007-01-17)

Per a vote of the XMPP Council, changed status to Deprecated. (psa)

Version 1.2 (2004-01-22)

Editorial revisions. (psa)

Version 1.1 (2004-01-06)

Added XML schema. (psa)

Version 1.0 (2002-10-15)

Changed status to Active. (psa)

Version 0.4 (2001-07-02)

Error codes update (rwe)

Version 0.3 (2001-06-29)

Protocol update (rwe)

Version 0.2 (2001-06-28)

DocBook version (psa)

Version 0.1 (2001-06-01)

Initial release (jer)

END