0.3

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@1197 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0215.xml

@@ -22,6 +22,12 @@
   <shortname>NOT YET ASSIGNED</shortname>
   &stpeter;
   &seanegan;
+  <revision>
+    <version>0.3</version>
+    <date>2007-08-30</date>
+    <initials>psa</initials>
+    <remark><p>Added name attribute for human-readable labels; added internationalization considerations; added security considerations.</p></remark>
+  </revision>
   <revision>
     <version>0.2</version>
     <date>2007-08-28</date>
@@ -67,10 +73,10 @@
 </header>
 
 <section1 topic='Introduction' anchor='intro'>
-  <p>An XMPP client 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 &rfc3489; and &rfc3489bis;) and STUN relays (see &turn;) for the sake of negotiating media exchanges via &xep0176;. <note>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 &lt;<link url='http://code.google.com/apis/talk/jep_extensions/jingleinfo.html'>http://code.google.com/apis/talk/jep_extensions/jingleinfo.html</link>&gt;, but has been broadened in scope to address additional use cases if desired.</note> An XMPP client can already discover such external services in several ways, including:</p>
+  <p>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 &rfc3489; and &rfc3489bis;) and STUN relays (see &turn;) for the sake of negotiating media exchanges via &xep0176;. <note>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 &lt;<link url='http://code.google.com/apis/talk/jep_extensions/jingleinfo.html'>http://code.google.com/apis/talk/jep_extensions/jingleinfo.html</link>&gt;, but has been broadened in scope to address additional use cases if desired.</note> An XMPP entity can already discover such external services in several ways, including:</p>
   <ol>
-    <li>The service is specified in the client's default settings.</li>
+    <li>The service is specified in the application's default settings.</li>
-    <li>The service is manually added into the client's configuration by a human user.</li>
+    <li>The service is manually added into the application's configuration by a human user.</li>
     <li>The service is discovered via non-XMPP service discovery protocols, such as:
       <ul>
         <li>DNS SRV records (&rfc2782;)</li>
@@ -82,13 +88,13 @@
       </ul>
     </li>
   </ol>
-  <p>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 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 client or server. This method does not use &xep0030; since that technology is designed for discovery of XMPP entities, not entities outside an XMPP network.</p>
+  <p>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.</p>
 </section1>
 
 <section1 topic='Protocol' anchor='protocol'>
-  <p>In order to learn about external services known to an XMPP server, a client sends an IQ-get containing an empty &lt;services/&gt; element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace &NSNOTE;, typically to its own server (but perhaps to a dedicated discovery service).</p>
+  <p>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 &lt;services/&gt; element qualified by the 'http://www.xmpp.org/extensions/xep-0215.html#ns' namespace &NSNOTE;, typically to its own server but perhaps alternatively to a dedicated discovery service.</p>
-  <p>The XMPP server (or service) SHOULD return the list of external services it is aware of, but MAY instead return an appropriate error, such as &unavailable; if the server 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 &lt;service/&gt; element.</p>
+  <p>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 &lt;service/&gt; element.</p>
-  <p>Note: The processes by which an XMPP server discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p>
+  <p>Note: The processes by which a responding entity discovers external services for "proxying" to XMPP entities are out of scope for this specification.</p>
   <p>The &lt;service/&gt; element MAY be empty or MAY include extended information about the service as described in the <link url='#extended'>Extended Information</link> section of this document.</p>
   <p>The attributes of the &lt;service/&gt; element are summarized in the following table.</p>
   <table caption='Attributes'>
@@ -102,6 +108,11 @@
       <td>Either a fully qualified domain name (FQDN) or an IP address (IPv4 or IPv6).</td>
       <td>REQUIRED</td>
     </tr>
+    <tr>
+      <td>name</td>
+      <td>A friendly (human-readable) name or label for the service.</td>
+      <td>OPTIONAL</td>
+    </tr>
     <tr>
       <td>password</td>
       <td>A service- or server-generated password for use at the service. *</td>
@@ -133,7 +144,7 @@
 
 <section1 topic='Use Cases' anchor='usecases'>
   <section2 topic='Requesting All Services' anchor='all'>
-    <p>A client requests all services by sending a &lt;services/&gt; element to its server.</p>
+    <p>A requesting entity requests all services by sending a &lt;services/&gt; element to its server or a discovery service.</p>
     <example caption='Entity Requests All External Services'><![CDATA[
 <iq type='get'
     from='bard@shakespeare.lit/globe'
@@ -161,6 +172,7 @@
              type='stun-relay'
              username='auu98sjl2wk3e9fjdsl7'/>
     <service host='ftp.shakespeare.lit' 
+             name='Shakespearean File Server'
              password='guest' 
              port='20' 
              transport='tcp' 
@@ -171,7 +183,7 @@
     ]]></example>
   </section2>
   <section2 topic='Requesting Selected Services' anchor='select'>
-    <p>A client requests selected services by sending a &lt;services/&gt; element to its server including a 'type' attribute specifying the service type of interest.</p>
+    <p>A requesting entity requests selected services by sending a &lt;services/&gt; element including a 'type' attribute specifying the service type of interest.</p>
     <example caption='Entity Requests Selected Services'><![CDATA[
 <iq type='get'
     from='bard@shakespeare.lit/globe'
@@ -201,7 +213,7 @@
   </services>
 </iq>
     ]]></example>
-    <p>If a client requests selected services, an XMPP server MAY as needed send an updated list of the relevant services by "pushing" the list to a client that has previously requested the list:</p>
+    <p>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).</p>
     <example caption='Services Push'><![CDATA[
 <iq type='set'
     from='shakespeare.lit'
@@ -267,6 +279,14 @@
   ]]></example>
 </section1>
 
+<section1 topic='Internationalization Considerations' anchor='i18n'>
+  <p>If the requesting entity includes an 'xml:lang' attribute with its request, the responding entity SHUOLD include appropriately internationalized text as the value of the 'name' attribute. No other attributes are human-readable.</p>
+</section1>
+
+<section1 topic='Security Considerations' anchor='security'>
+  <p>Because the responding entity (XMPP server or discovery service) functions as a "proxy" from external services to the XMPP network, it could modify the information it receives before passing it on to the requesting entity.</p>
+</section1>
+
 <section1 topic='XMPP Registrar Considerations' anchor='registrar'>
   <section2 topic='Protocol Namespaces' anchor='ns'>
     <p>Until this specification advances to a status of Draft, its associated namespace shall be "http://www.xmpp.org/extensions/xep-0215.html#ns"; upon advancement of this specification, the XMPP Registrar shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;.</p>
@@ -304,6 +324,7 @@
       <xs:simpleContent>
         <xs:extension base='empty'>
           <xs:attribute name='host' type='xs:string' use='required'/>
+          <xs:attribute name='name' type='xs:string' use='optional'/>
           <xs:attribute name='password' type='xs:string' use='optional'/>
           <xs:attribute name='port' type='xs:string' use='required'/>
           <xs:attribute name='transport' type='xs:NCName' use='optional'/>