Direct connection is the simpler case. In this situation, the StreamHost is the Initiator (StreamHost/Initiator), which means that the Initiator knows the network address of the StreamHost and knows when to activate the bytestream. The process for establishing bytestreams in this case is as follows:

1. Initiator sends IQ-set to Target specifying the full JID and network address of StreamHost/Initiator as well as the StreamID (SID) of the proposed bytestream.

2. Target opens a TCP socket to the specified network address.

3. Target requests connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.

4. StreamHost/Initiator sends acknowledgement of successful connection to Target via SOCKS5.

5. Target sends IQ-result to Initiator, preserving the 'id' of the initial IQ-set.

6. StreamHost/Initiator activates the bytestream.

7. Initiator and Target may begin using the bytestream.

Mediated connection is slightly more complicated. In this situation, the StreamHost is not the Initiator but a Proxy, which means that the Initiator must discover the network address of the StreamHost before sending the initial IQ-set, must negotiate a connection with the StreamHost in the same way that the Target does, and must request that the StreamHost activate the bytestream before it can be used. The process for establishing bytestreams in this case is as follows:

1. Optionally, Initiator discovers the network address of StreamHost in-band.

2. Initiator sends IQ-set to Target specifying the full JID and network address of StreamHost as well as the StreamID (SID) of the proposed bytestream.

3. Target opens a TCP socket to the selected StreamHost.

4. Target establishes connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.

5. StreamHost sends acknowledgement of successful connection to Target via SOCKS5.

6. Target sends IQ-result to Initiator, preserving the 'id' of the initial IQ-set.

7. Initiator opens a TCP socket at the StreamHost.

8. Initiator establishes connection via SOCKS5, with the DST.ADDR and DST.PORT parameters set to the values defined below.

9. StreamHost sends acknowledgement of successful connection to Initiator via SOCKS5.

10. Initiator sends IQ-set to StreamHost requesting that StreamHost activate the bytestream associated with the StreamID.

11. StreamHost activates the bytestream. (Data is now relayed between the two SOCKS5 connections by the proxy.)

12. StreamHost sends IQ-result to Initiator acknowledging that the bytestream has been activated (or specifying an error).

13. Initiator and Target may begin using the bytestream.

Before attempting to initiate a bytestream, the Initiator may want to know if the Target supports the bytestream protocol. It may do so using &jep0030; as follows:

If the Target supports bytestreams, it MUST answer to that effect in the service discovery result.

Before attempting to initiate a bytestream, the Initiator needs to find a proxy. It may do so using Service Discovery as follows:

The server will return all of the known JIDs in its disco list.

For each item in the disco#items result, the Initiator must query to determine if it is a bytestreams proxy. It may do so using Service Discovery as follows:

The proxy will return its information. The Initiator SHOULD inspect each identity to see if it contains an identity of category "proxy" and type "bytestreams".

If the StreamHost is a Proxy, the Initiator must first request the full network address used for bytestreaming (obviously this is not required if the StreamHost is the Initiator). This is done by sending an IQ-get to the proxy in the bytestreams namespace, as follows:

The <streamhost/> element specifying a network address MUST possess the following attributes:

• jid = the JID of the StreamHost for communications over Jabber

In addition, the <streamhost/> element MUST include:

EITHER

• host = the hostname or IP address of the StreamHost for SOCKS5 communications over TCP
• port = a port associated with the hostname or IP address for SOCKS5 communications over TCP

OR

• zeroconf = a zeroconf Zeroconf is a set of protocols that enable IP networking without the need for configuration. For further information, refer to <http://www.zeroconf.org/>. identifier to which an entity may connect, for which the service identifier and protocol name SHOULD be "_jabber.bytestreams".

If the Initiator does not have permissions to initiate bytestreams on the Proxy for whatever reason (e.g., a proxy implementation may enable administrators to ban JIDs or domains from using the Proxy), the Proxy MUST return a &forbidden; error to the Initiator (for information about error syntax, refer to &jep0086;):

If the Proxy is unable to act as a StreamHost, the Proxy SHOULD return a ¬allowed; error to the Initiator:

In order to establish a bytestream between the Initiator and the Target, the Initiator must provide network address information for the StreamHost(s) to the Target. This happens in-band via a single IQ-set, which must contain the following information:

• The network address of at least one StreamHost to which the Target may attempt to connect
• The Stream ID for this connection
• The "mode" to use, normally "tcp" but optionally "udp" (see the Optional UDP Support section of this document)

The protocol format is shown below.

If the Target is unwilling to accept the bytestream, it MUST return a ¬acceptable; error to the Initiator.

If the Target is willing to accept the bytestream, it MUST attempt to open a standard TCP socket on the network address of the StreamHost communicated by the Initiator. If the Initiator provides more than one StreamHost, the Target SHOULD try to connect to them in the order they occur.

If the Target tries but is unable to connect to any of the StreamHosts and it does not wish to attempt a connection from its side, it MUST return a ¬found; error to the Initiator.

If the Target is able to open a TCP socket on a StreamHost, it MUST utilize the SOCKS5 protocol specified in &rfc1928; to establish the connection with the StreamHost. In accordance with the SOCKS5 RFC, the Target MAY have to authenticate in order to use the proxy. However, any authentication required is beyond the scope of this JEP.

Once the Target has successfully authenticated with the Proxy (even anonymously), it SHOULD send a CONNECT request to a host named: SHA1(SID + Initiator JID + Target JID), port 0, where the SHA1 hashing algorithm is specified by &rfc3174;. The JIDs provided MUST be full JIDs (i.e., <user@host/resource>); furthermore, in order to ensure proper results, the appropriate stringprep profiles (as specified in &xmppcore;) MUST be applied to the JIDs before application of the SHA1 hashing algorithm.

After the Target has authenticated with the StreamHost, it MUST send an IQ-result to the Initiator indicating which StreamHost was used.

At this point, the Initiator knows which StreamHost was used by the Target.

If the StreamHost used is a Proxy, the Initiator MUST authenticate and establish a connection with the StreamHost before requesting that the StreamHost activate bytestream. The Initiator will establish a connection to the SOCKS5 proxy in the same way the Target did, passing the same value for the CONNECT request.

In order for the bytestream to be used, it MUST first be activated by the StreamHost. If the StreamHost is the Initiator, this is straightforward and does not require any in-band protocol. However, if the StreamHost is a Proxy, the Initiator MUST send an in-band request to the StreamHost. This is done by sending an IQ-set to the Proxy, including an <activate/> element whose XML character data specifies the full JID of the Target.

Using this information, with the SID and from address on the packet, the Proxy is able to activate the stream by hashing the SID + Initiator JID + Target JID. This provides a reasonable level of trust that the activation request came from the Initiator.

If the Proxy can fulfill the request, it MUST then respond to the Initiator with an IQ-result.

The Proxy MUST then send SOCKS5 acknowledgement of the connection to the Target.

If the Proxy cannot fulfill the request, it MUST return an IQ-error to the Initiator; the following conditions are defined:

• ¬found; error if the from address does not match that of the Initiator's full JID
• ¬allowed; error if only one party (either Initiator or Recipient, but not both) is connected to the Proxy
• &internalserver; error if the proxy cannot activate the bytestream because of some internal malfunction

1. Initiator wishes to establish a bytestream with Target
2. Initiator sends an IQ-set to Target specifying a StreamID and the network addresses of one or more StreamHosts [A1]
3. Target wishes to establish a bytestream with Initiator [A2]
4. Target requests TCP connection with a StreamHost [A3]
5. Target receives TCP acknowledgement from StreamHost [A4]
6. Target provides authentication credentials to StreamHost via SOCKS5
7. Target receives acknowledgement of authentication with StreamHost via SOCKS5 [A5]
8. Target requests connection with StreamHost via SOCKS5
9. Target receives acknowledgement of successful connection with StreamHost via SOCKS5 [A7]
10. Target sends IQ-result to Initiator announcing successful connection to StreamHost [A6]
11. Use Case Ends (bytestream is established and ready for use)

A1. Initiator does not know the full network address of a StreamHost (i.e., Proxy)

1. Initiator sends IQ-get to Proxy
2. Initiator receives IQ-result from Proxy containing network address [A9][A10]
3. Return to P2

A2. Target does not wish to establish a bytestream with Initiator

1. Initiator receives ¬acceptable; error from Target
2. UCE unsuccessfully

A3. No more StreamHosts in list (Target is unable to reach any of the provided StreamHosts)

1. Target returns &remoteserver; error to Initiator
2. UCE unsuccessfully

A4. Target cannot reach StreamHost

1. Return to P4

A5. Target authentication with StreamHost fails

1. Return to P4

A6. Proxy is unwilling to act as a StreamHost for Initiator

1. Initiator receives &forbidden; error from Proxy
2. Return to P2

A7. Proxy is unable to act as a StreamHost for Initiator

1. Initiator receives ¬allowed; error from Proxy
2. Return to P2

A8. Target connects to a Proxy

1. Initiator reaches Proxy [A9]
2. Target receives TCP acknowledgement from StreamHost [A9]
3. Initiator authenticates with Proxy via SOCKS5
4. Initiator receives acknowledgement of authentication with Proxy via SOCKS5 [A10]
5. Initiator requests connection with Proxy via SOCKS5
6. Initiator receives acknowledgement of successful connection with Proxy via SOCKS5 [A11]
7. Initiator sends IQ-set to Proxy requesting activation of bytestream
8. Initiator receives IQ-result from Proxy acknowledging activation of bytestream [A12]
9. Return to P9

A9. Initiator is unable to reach Proxy

1. UCE unsuccessfully

A10. Initiator is unable to authenticate with Proxy

1. UCE unsuccessfully

A11. Initiator is unable to connect to Proxy

1. UCE unsuccessfully

A12. Proxy is unable to activate bytestream

1. Initiator receives &internalserver; error from Proxy
2. UCE unsuccessfully

The <query/> element is the container for all in-band communications. This element MUST be in the namespace "http://jabber.org/protocol/bytestreams". This element has a single attribute for the stream session identifier, and contains multiple <streamhost/> elements, a single <streamhost-used/> element, or a single <activate/> element.

The "sid" specifies the bytestream session identifier. This attribute MUST be present. The value of this attribute is any character data.

The "mode" specifies the mode to use, either 'tcp' or 'udp'. If this attribute is missing, the default value of "tcp" MUST be assumed.

The <streamhost/> element conveys the network connection information. At least one instance MUST be present in the initial IQ-set from the Initiator to the Target. If multiple instances of this element are present, each one MUST be a separate host/port combination.

The <streamhost-used/> element transports the out-of-band token. It MUST be present in the IQ-set from the Target to the Initiator, and there MUST be only one instance.

The <activate/> element is used to request activation of a unidirectional or bidirectional bytestream. It MUST be present in the IQ-set sent from the Initiator to the StreamHost after the Initiator receives an IQ-result from the Target, and there MUST be only one instance.

The <streamhost/> element contains the bytestream connection information. This element has attributes for the StreamHost's JID, network host/address, and network port. This element MUST NOT contain any content nodes.

The "jid" attribute specifies the StreamHost's JID. This attribute MUST be present, and MUST be a valid JID for use with an <iq/>.

The "host" attribute specifies the host to connect to. This attribute MUST be present. The value MUST be either a resolvable domain name or the "dotted decimal" IP address (e.g. "1.2.3.4").

The "port" attribute specifies the port to connect to. This attribute MAY be present. The value MUST be a valid port number in decimal form.

The "zeroconf" attribute specifies the zero-configuration service available for bytestreaming. This attribute SHOULD be present. The value SHOULD be '_jabber.bytestreams'.

When communicating the available hosts, the Initiator MUST include EITHER the host and port OR the zeroconf information.

The <streamhost-used/> element indicates the StreamHost connected to. This element has a single attribute for the JID of the StreamHost to which the Target connected. This element MUST NOT contain any content node.

The "jid" attribute specifies the full JID of the StreamHost. This attribute MUST be present, and MUST be a valid JID for use with an <iq/>.

The <activate/> element is a flag to trigger a Proxy to complete a connection.

If an implementation supports UDP associations, it MUST advertise that separately by returning a feature of 'http://jabber.org/protocol/bytestreams#udp' in response to Service Discovery information requests.

If the Target supports UDP associations, it MUST answer to that effect in the service discovery result.

UDP associations are requested by setting the 'mode' attribute to a value of "udp" rather than "tcp".

There is one main difference between UDP mode and TCP mode: rather than simply establishing a TCP connection, the Target and/or Initiator MUST (1) establish a UDP association and then (2) initialize the UDP channel. In particular:

• If direct connection is followed, Target MUST complete UDP association and initialization of the UDP channel before informing Initiator of success via the <streamhost-used/> element.
• If mediated connection is followed, (1) Target MUST complete UDP association and initialization of the UDP channel before informing Initiator of success via the <streamhost-used/> element, and (2) Initiator MUST complete UDP association and initialization of the UDP channel before asking StreamHost to activate the bytestream.

The processes for establishing the UDP association and for initializing the UDP channel are described below.

Once the UDP association is established, UDP packets can be exchanged with the StreamHost. When a UDP packet is sent by either party, it MUST contain a 4-byte header (in addition to other possible headers, such as that of SOCKS5), which consists of the source virtual port and then the destination virtual port of the packet, both 16-bit values in network byte order. This allows the peers to multiplex many packets for different purposes over one session. The actual application data should follow this header, and thus the payload size will always be "Application Data Size + 4".

For all packets sent to the StreamHost, DST.PORT is set to 0, and DATA contains the payload.

UDP packets sent from the StreamHost do not have any SOCKS5 headers, and so the payload should be delivered as-is.

The programming interface for a SOCKS5 Bytestreams-aware UDP MUST report an available buffer space for UDP datagrams that is smaller than the actual space provided by the operating system and SOCKS5 layer if applicable. In other words, 4 more octets smaller.

A StreamHost MUST support TCP connections.

A StreamHost SHOULD:

1. Allow bi-directional bytestreaming between the Initiator and Target.
2. Allow only one Target to connect to a bytestream (i.e., disallow multicasting).
3. Track sessions based on a combination of the StreamID and the Initiator's full JID, thus allowing an Initiator to create more than one simultaneous session.
4. Ignore but not drop any bytes sent before the bytestream is activated.
5. Prefer to use zero-configuration IP networking if supported.

A StreamHost MAY:

1. Support UDP associations in addition TCP connections.
2. Ignore the DST.ADDR and DST.PORT parameters if desired.

To facilitate the usage of SOCKS5, command parameters MUST be mapped to the appropriate values. Parameters not specified in the table below SHOULD be used as defined in RFC 1928.

The ®ISTRAR; includes 'http://jabber.org/protocol/bytestreams' in its registry of protocol namespaces.

The Jabber Registrar shall includes 'http://jabber.org/protocol/bytestreams#udp' in its registry of service discovery features.

The Jabber Registrar includes the "proxy" category and associated "bytestreams" type in the Service Discovery registry. The registry submission is as follows: