From 789f15ebe70ed0e6e2b82efd90e46712f71e2570 Mon Sep 17 00:00:00 2001 From: Peter Saint-Andre Date: Thu, 18 Feb 2010 04:51:00 +0000 Subject: [PATCH] 0.5 published git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3940 4b5297f7-1745-476d-ba37-a9c6900126ab --- xep-0215.xml | 162 ++++++++++++++++++++++++++++++--------------------- 1 file changed, 96 insertions(+), 66 deletions(-) diff --git a/xep-0215.xml b/xep-0215.xml index 9261465b..9b6a6474 100644 --- a/xep-0215.xml +++ b/xep-0215.xml @@ -22,12 +22,13 @@ extdisco &stpeter; &seanegan; - - Marcus - Lundblad - ml@update.uu.se - mlundblad@jabber.org - + &mlundblad; + + 0.5 + 2010-02-17 + psa +

Added ability to request credentials from a particular service; incremented the protocol version number to reflect the new feature.

 + 0.4 2009-02-17 @@ -85,7 +86,7 @@ -

An XMPP client or other entity may need to discover services external to the XMPP network in order to complete certain XMPP-related use cases. One example is the discovery of STUN servers (see &rfc5389;) and STUN relays (see &turn;) for the sake of negotiating media exchanges via &xep0176;. The protocol specified herein is functionally equivalent to the protocol currently used in the Google Talk service for discovery of STUN servers, as documented at <http://code.google.com/apis/talk/jep_extensions/jingleinfo.html>, but has been broadened in scope to address additional use cases if desired. An XMPP entity can already discover such external services in several ways, including:

+

An XMPP client or other entity might need to discover services external to the XMPP network in order to complete certain XMPP-related use cases. One example is the discovery of STUN servers (see &rfc5389;) and TURN relays (see &turn;) for the sake of negotiating media exchanges via &xep0176;. The protocol specified herein is functionally equivalent to the protocol currently used in the Google Talk service for discovery of STUN servers, as documented at <http://code.google.com/apis/talk/jep_extensions/jingleinfo.html>, but has been broadened in scope to address additional use cases if desired. An XMPP entity can already discover such external services in several ways, including:

  1. The service is specified in the application's default settings.
  2. The service is manually added into the application's configuration by a human user.
    3. @@ -100,11 +101,11 @@
-

Unfortunately, some of the foregoing methods are subject to human error and others are either not widely available or cannot be deployed in wide range of scenarios (e.g., when the administrators of an XMPP service do not have access to DNS SRV records). Therefore, this document defines a way for an XMPP server or discovery service to provide information about external services, which may include extended information such as temporary credentials for authentication at such services. This method should be used only as a fallback when the relevant service discovery technologies (DNS SRV, DDDS, SLP, S-NAPTR, U-NAPTR, etc.) are not available to the XMPP entities involved (typically a client and server). This method does not use &xep0030; since that technology is designed for discovery of XMPP entities, not entities outside an XMPP network.

+

Unfortunately, some of the foregoing methods are subject to human error and others are either not widely available or cannot be deployed in wide range of scenarios (e.g., when the administrators of an XMPP service do not have access to DNS SRV records). Therefore, this document defines a way for an XMPP server or discovery service to provide information about external services, which might include extended information such as temporary credentials for authentication at such services. This method SHOULD be used only as a fallback when the relevant service discovery technologies (DNS SRV, DDDS, SLP, S-NAPTR, U-NAPTR, etc.) are not available to the XMPP entities involved (typically a client and server). This method does not use &xep0030; since that technology is designed for discovery of XMPP entities, not entities outside an XMPP network.

 -

In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty <services/> element qualified by the 'urn:xmpp:extdisco:0' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.

+

In order to learn about external services known to an XMPP server or discovery service, a requesting entity (typically a client) sends an IQ-get containing an empty <services/> element qualified by the 'urn:xmpp:extdisco:1' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.

The responding entity (XMPP server or discovery service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as &unavailable; if the responding entity does not support this protocol or &forbidden; if the requesting entity does not have permission to receive the list of external services. Each service is encapsulated via a <service/> element.

Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.

The <service/> element MAY be empty or MAY include extended information about the service as described in the Extended Information section of this document.

@@ -151,26 +152,26 @@ OPTIONAL -

* Note: The processes by which an external service might generate or an XMPP server might negotiate the username and password are outside the scope of this specification. One possible approach is for the XMPP server to generate a short-term authentication credential based on a private key shared with the external service.

+

* Note: The processes by which an external service might generate (or an XMPP server might negotiate) the username and password are outside the scope of this specification. One possible approach is for the XMPP server to generate a short-term authentication credential based on a private key shared with the external service.

A requesting entity requests all services by sending a <services/> element to its server or a discovery service.

- + type='get'> + ]]> - + type='result'> + -

A requesting entity requests selected services by sending a <services/> element including a 'type' attribute specifying the service type of interest.

+

A requesting entity requests services of a particular type by sending a <services/> element including a 'type' attribute specifying the service type of interest.

- + type='get'> + ]]> - + ]]> -

If a requesting entity requests selected services, the responding service MAY as needed send an updated list of the relevant services by "pushing" the list to a requesting entity that has previously requested the list. However, it MUST NOT push updates to the requesting entity unless it has presence information about the requesting entity (e.g., because the requesting entity is connected to the XMPP server or because the requesting entity has shared presence with a remote discovery service).

+

If a requesting entity requests services of a particular type, the responding service MAY as needed send an updated list of the relevant services by "pushing" the list to a requesting entity that has previously requested the list. However, it MUST NOT push updates to the requesting entity unless it has presence information about the requesting entity (e.g., because the requesting entity is connected to the XMPP server or because the requesting entity has shared presence with a remote discovery service). A push is an IQ set to the requesting entity containing a <service/> payload with updated data about services matching the requested type (e.g., new services or updated credentials)

- + ]]> +

Upon receiving a push, the requesting entity would then send an IQ-result to the responding service in accordance with &xmppcore;.

+ + +

An entity might know about an external service via DNS or some other means, but still might need short-term credentials to use the service. The entity can request credentials by sending a special request to the server.

+ + + + + + ]]> +

The server then returns credentials if possible.

+ + + + + + ]]> +

If the server cannot obtain credentials at the service, it returns an appropriate stanza error, such as ¬found;, &remoteserver;, &timeout;, or ¬authorized;.

 -

If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the <value/> child of a distinct <field/> element, with the entire set of fields contained within an <x/> element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this <x/> element SHOULD be a child of the <service/> element qualified by the 'urn:xmpp:extdisco:0' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:

+

If a server or service needs to include extended information, it SHOULD do so by including each bit of information as the XML character data of the <value/> child of a distinct <field/> element, with the entire set of fields contained within an <x/> element of type "result" qualified by the 'jabber:x:data' namespace (see &xep0004;); this <x/> element SHOULD be a child of the <service/> element qualified by the 'urn:xmpp:extdisco:1' namespace &NSNOTE;. Thus the IQ result SHOULD be of the following form:

- + @@ -276,27 +305,27 @@ ]]>

Note: A <field/> element MAY contain more than one <value/> child if appropriate.

-

If the data fields are to be used in the context of a protocol approved by the XMPP Standards Foundation, they SHOULD be registered in accordance with the rules defined in XEP-0068, resulting in the inclusion of a <field/> element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".

-

Note: Although &xep0128; specifies that an XMPP entity MUST NOT supply extended information about associated children communicated via the 'urn:xmpp:extdisco:0' namespace, that rule does not apply to External Service Discovery since services external to the XMPP network cannot communicate via XMPP.

+

If the data fields are to be used in the context of a protocol approved by the XMPP Standards Foundation, they SHOULD be registered in accordance with the rules defined in &xep0068;, resulting in the inclusion of a <field/> element whose 'var' attribute has a value of "FORM_TYPE" and whose 'type' attribute has a value of "hidden".

+

Note: Although &xep0128; specifies that an XMPP entity MUST NOT supply extended information about associated children communicated via the 'http://jabber.org/protocol/disco#info' namespace, that rule does not apply to External Service Discovery since services external to the XMPP network cannot communicate via XMPP.

 -

If an entity supports the STUN Server Discovery protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:0" &NSNOTE; in response to a &xep0030; information request:

+

If an XMPP entity supports this protocol, it MUST report that fact by including a service discovery feature of "urn:xmpp:extdisco:1" &NSNOTE; in response to a &xep0030; information request:

+ type='get'> ]]> + type='result'> - + ]]> @@ -314,7 +343,7 @@

This specification defines the following XML namespace:

    -
  • urn:xmpp:extdisco:0
    • +
  • urn:xmpp:extdisco:1

Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.

 @@ -332,7 +361,7 @@ the document that best defines the service type ]]> -

The registrant may register more than one service type at a time, each contained in a separate <service/> element.

+

The registrant can register more than one service type at a time, each contained in a separate <service/> element.

- + - - - - - - - - - - - + + + - - - - - + + + + + + + + + + + + + + ]]> -

Thanks to Justin Karneges and Unnikrishnan Vikrama Panicker for their feedback.

+

Thanks to Justin Karneges, Evgeniy Khramtsov, and Unnikrishnan Vikrama Panicker for their feedback.