xeps/xep-0077.xml

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
  <!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<xep>
<header>
  <title>In-Band Registration</title>
  <abstract>This specification defines an XMPP protocol extension for in-band registration with XMPP-based instant messaging servers and other services hosted on an XMPP network (such as groupchat rooms and gateways to non-XMPP IM services). The protocol is extensible via use of data forms, thus enabling services to gather a wide range of information during the registration process. The protocol also supports in-band password changes and cancellation of an existing registration.</abstract>
  &LEGALNOTICE;
  <number>0077</number>
  <status>Final</status>
  <type>Standards Track</type>
  <sig>Standards</sig>
  <approver>Council</approver>
  <dependencies>
    <spec>XMPP Core</spec>
  </dependencies>
  <supersedes/>
  <supersededby/>
  <shortname>iq-register</shortname>
  <schemaloc>
    <url>http://www.xmpp.org/schemas/iq-register.xsd</url>
  </schemaloc>
  &stpeter;
  <revision>
    <version>2.4</version>
    <date>2012-01-25</date>
    <initials>psa</initials>
    <remark><p>Defined service discovery support.</p></remark>
  </revision>
  <revision>
    <version>2.3</version>
    <date>2009-09-15</date>
    <initials>psa</initials>
    <remark><p>Clarified that fields for "first" and "last" in fact always represent given name and family name, respectively.</p></remark>
  </revision>
  <revision>
    <version>2.2</version>
    <date>2006-01-24</date>
    <initials>psa</initials>
    <remark><p>Further specified integration with data forms, specifically if needed to require additional information when cancelling an existing registration (e.g., username and password) or changing a password (e.g., old password); also clarified server handling of cancelled registrations.</p></remark>
  </revision>
  <revision>
    <version>2.1</version>
    <date>2005-07-14</date>
    <initials>psa</initials>
    <remark><p>Clarified the extensibility rules; removed expiration date; modified schema to document optional inclusion of jabber:x:data and jabber:x:oob information.</p></remark>
  </revision>
  <revision>
    <version>2.0</version>
    <date>2004-08-30</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the Jabber Council, advanced status to Final; also specified that by server is meant an instant messaging server.</p></remark>
  </revision>
  <revision>
    <version>1.6</version>
    <date>2004-08-23</date>
    <initials>psa</initials>
    <remark><p>In order to address Council concerns, clarified precedence order of x:data, iq:register, and x:oob; further specified server handling of initial registration requests from unregistered entities.</p></remark>
  </revision>
  <revision>
    <version>1.5</version>
    <date>2004-07-21</date>
    <initials>psa</initials>
    <remark><p>Specified server handling of requests from unregistered entities.</p></remark>
  </revision>
  <revision>
    <version>1.4</version>
    <date>2004-05-10</date>
    <initials>psa</initials>
    <remark><p>Removed conformance language regarding servers and services (belongs in a protocol suite specification).</p></remark>
  </revision>
  <revision>
    <version>1.3</version>
    <date>2004-02-24</date>
    <initials>psa</initials>
    <remark><p>Added text about redirection to web registration.</p></remark>
  </revision>
  <revision>
    <version>1.2</version>
    <date>2003-11-26</date>
    <initials>psa</initials>
    <remark><p>Documented use of &lt;key/&gt; element; added optional stream feature; added XMPP error handling; specified handling of empty passwords.</p></remark>
  </revision>
  <revision>
    <version>1.1</version>
    <date>2003-10-02</date>
    <initials>psa</initials>
    <remark><p>Moved change password use case from XEP-0078.</p></remark>
  </revision>
  <revision>
    <version>1.0</version>
    <date>2003-06-18</date>
    <initials>psa</initials>
    <remark><p>Per a vote of the Jabber Council, advanced status to Draft.</p></remark>
  </revision>
  <revision>
    <version>0.9</version>
    <date>2003-06-18</date>
    <initials>psa</initials>
    <remark><p>Changes to address Council concerns.</p></remark>
  </revision>
  <revision>
    <version>0.8</version>
    <date>2003-06-13</date>
    <initials>psa</initials>
    <remark><p>Restored the &lt;misc/&gt; and &lt;text/&gt; elements; added the old &lt;key/&gt; element; specified these three elements as obsolete.</p></remark>
  </revision>
  <revision>
    <version>0.7</version>
    <date>2003-06-12</date>
    <initials>psa</initials>
    <remark><p>Added &lt;registered/&gt; element; specified FORM_TYPE for x:data form; clarified that support for the extensibility mechanism is optional; removed the &lt;misc/&gt; and &lt;text/&gt; elements (not necessary given extensibility option); added &lt;nick/&gt;, &lt;first/&gt;, and &lt;last/&gt; elements that were traditionally documented as part of jabber:iq:register.</p></remark>
  </revision>
  <revision>
    <version>0.6</version>
    <date>2003-06-06</date>
    <initials>psa</initials>
    <remark><p>Removed XMPP-style error conditions until formats are stable.</p></remark>
  </revision>
  <revision>
    <version>0.5</version>
    <date>2003-05-30</date>
    <initials>psa</initials>
    <remark><p>Removed "encrypted secret" content, added information about expiration date.</p></remark>
  </revision>
  <revision>
    <version>0.4</version>
    <date>2003-05-28</date>
    <initials>psa</initials>
    <remark><p>Added "encrypted secret" content.</p></remark>
  </revision>
  <revision>
    <version>0.3</version>
    <date>2003-05-20</date>
    <initials>psa</initials>
    <remark><p>Slight editorial revisions.</p></remark>
  </revision>
  <revision>
    <version>0.2</version>
    <date>2003-04-29</date>
    <initials>psa</initials>
    <remark><p>Fixed schema, made minor editorial changes.</p></remark>
  </revision>
  <revision>
    <version>0.1</version>
    <date>2003-04-06</date>
    <initials>psa</initials>
    <remark><p>Initial version.</p></remark>
  </revision>
</header>
<section1 topic='Introduction' anchor='intro'>
  <p>The Jabber protocols have long included a method for in-band registration with instant messaging servers and associated services. This method makes use of the 'jabber:iq:register' namespace and has been documented variously in Internet-Drafts and elsewhere. Because in-band registration is not required by &rfc2779;, documentation of the 'jabber:iq:register' namespace was removed from &xmppim;. This specification fills the void for canonical documentation.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
  <p>In-band registration must make it possible for an entity to register with a host, cancel an existing registration with a host, or change a password with a host. By "host" is meant either of the following:</p>
  <ol>
    <li>an instant messaging server, such as described in <cite>XMPP IM</cite> and identified by the "server/im" &xep0030; category+type</li>
    <li>an add-on service, such as a gateway (see &xep0100;) or a &xep0045; service</li>
  </ol>
  <p>If needed, extensibility with regard to information gathered should be done using &xep0004;.</p>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
  <section2 topic='Entity Registers with a Host' anchor='usecases-register'>
    <p>In order to determine which fields are required for registration with a host, an entity SHOULD first send an IQ get to the host. The entity SHOULD NOT attempt to guess at the required fields by first sending an IQ set, since the nature of the required data is subject to service provisioning.</p>
    <example caption='Entity Requests Registration Fields from Host'><![CDATA[
<iq type='get' id='reg1' to='shakespeare.lit'>
  <query xmlns='jabber:iq:register'/>
</iq>
]]></example>
    <p>If the entity is not already registered and the host supports In-Band Registration, the host MUST inform the entity of the required registration fields. If the host does not support In-Band Registration, it MUST return a &unavailable; error. If the host is redirecting registration requests to some other medium (e.g., a website), it MAY return an &lt;instructions/&gt; element only, as shown in the <link url="#redirect">Redirection</link> section of this document.</p>
    <example caption='Host Returns Registration Fields to Entity'><![CDATA[
<iq type='result' id='reg1'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      Choose a username and password for use with this service.
      Please also provide your email address.
    </instructions>
    <username/>
    <password/>
    <email/>
  </query>
</iq>
]]></example>
    <p>If the host determines (based on the 'from' address) that the entity is already registered, the IQ result that it sends in response to the IQ get MUST contain an empty &lt;registered/&gt; element (indicating that the entity is already registered), SHOULD contain the registration information currently on file for the entity (although the &lt;password/&gt; element MAY be empty), and SHOULD contain an &lt;instructions/&gt; element (whose XML character data MAY be modified to reflect the fact that the entity is currently registered).</p>
    <p>If the host is an instant messaging server, it SHOULD assume that the requesting entity is unregistered at this stage unless the entity has already authenticated (for details, see the <link url="#usecases-register-server">Registration with a Server</link> section below).</p>
    <example caption='Host Informs Entity of Current Registration'><![CDATA[
<iq type='result' id='reg1'>
  <query xmlns='jabber:iq:register'>
    <registered/>
    <username>juliet</username>
    <password>R0m30</password>
    <email>juliet@capulet.com</email>
  </query>
</iq>
]]></example>
    <p>If the entity is not already registered, the entity SHOULD provide the required information.</p>
    <example caption='Entity Provides Required Information'><![CDATA[
<iq type='set' id='reg2'>
  <query xmlns='jabber:iq:register'>
    <username>bill</username>
    <password>Calliope</password>
    <email>bard@shakespeare.lit</email>
  </query>
</iq>
]]></example>
    <p>Note: The requesting entity MUST provide information for all of the elements (other than &lt;instructions/&gt;) contained in the IQ result.</p>
    <example caption='Host Informs Entity of Successful Registration'><![CDATA[
<iq type='result' id='reg2'/>
]]></example>
    <p>Alternatively, registration may fail. Possible causes of failure include a username conflict (the desired username is already in use by another entity) and the fact that the requesting entity neglected to provide all of the required information.</p>
    <example caption='Host Informs Entity of Failed Registration (Username Conflict)'><![CDATA[
<iq type='error' id='reg2'>
  <query xmlns='jabber:iq:register'>
    <username>bill</username>
    <password>m1cro$oft</password>
    <email>billg@bigcompany.com</email>
  </query>
  <error code='409' type='cancel'>
    <conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <p>If the requesting entity does not provide all of the requested information during registration <note>This includes providing an empty password element or a password element that contains no XML character data, i.e., either &lt;password/&gt; or &lt;password&gt;&lt;/password&gt;.</note> then the server or service MUST return a &notacceptable; error to the requesting entity.</p>
    <example caption='Host Informs Entity of Failed Registration (Some Required Information Not Provided)'><![CDATA[
<iq type='error' id='reg2'>
  <query xmlns='jabber:iq:register'>
    <username>bill</username>
    <password>Calliope</password>
  </query>
  <error code='406' type='modify'>
    <not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <p>If the host requires additional information above and beyond the data elements specified in the schema, it SHOULD use Data Forms as described in the <link url='#extensibility'>Extensibility</link> section of this document. (The next three examples show registration of an existing account with a third-party service, not of an entity with a server for the purpose of account registration.)</p>
    <example caption='Entity Requests Registration Fields from Host'><![CDATA[
<iq type='get'
    from='juliet@capulet.com/balcony'
    to='contests.shakespeare.lit'
    id='reg3'>
  <query xmlns='jabber:iq:register'/>
</iq>
]]></example>
    <example caption='Host Returns Registration Form to Entity'><![CDATA[
<iq type='result'
    from='contests.shakespeare.lit'
    to='juliet@capulet.com/balcony'
    id='reg3'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      Use the enclosed form to register. If your Jabber client does not
      support Data Forms, visit http://www.shakespeare.lit/contests.php
    </instructions>
    <x xmlns='jabber:x:data' type='form'>
      <title>Contest Registration</title>
      <instructions>
        Please provide the following information
        to sign up for our special contests!
      </instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>jabber:iq:register</value>
      </field>
      <field type='text-single' label='Given Name' var='first'>
        <required/>
      </field>
      <field type='text-single' label='Family Name' var='last'>
        <required/>
      </field>
      <field type='text-single' label='Email Address' var='email'>
        <required/>
      </field>
      <field type='list-single' label='Gender' var='x-gender'>
        <option label='Male'><value>M</value></option>
        <option label='Female'><value>F</value></option>
      </field>
    </x>
  </query>
</iq>
]]></example>
    <p>The user then SHOULD return the form:</p>
    <example caption='User Submits Registration Form'><![CDATA[
<iq type='set'
    from='juliet@capulet.com/balcony'
    to='contests.shakespeare.lit'
    id='reg4'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='submit'>
      <field type='hidden' var='FORM_TYPE'>
        <value>jabber:iq:register</value>
      </field>
      <field type='text-single' label='Given Name' var='first'>
        <value>Juliet</value>
      </field>
      <field type='text-single' label='Family Name' var='last'>
        <value>Capulet</value>
      </field>
      <field type='text-single' label='Email Address' var='email'>
        <value>juliet@capulet.com</value>
      </field>
      <field type='list-single' label='Gender' var='x-gender'>
        <value>F</value>
      </field>
    </x>
  </query>
</iq>
]]></example>
    <section3 topic='Registration with a Server' anchor='usecases-register-server'>
      <p>Special care must be taken when an unregistered entity interacts with a server rather than a service. Normally, a server enables in-band registration so that entities can "bootstrap" their participation in the Jabber network; this bootstrapping happens when an unregistered and unauthenticated entity opens a TCP connection to a server and immediately completes the registration use case with the server, then authenticates using the newly-registered identity. As noted, when a server receives an IQ-get for registration information, it SHOULD assume that the requesting entity is unregistered unless the entity has already authenticated.</p>
      <p>Depending on local service provisioning, a server MAY return a &notacceptable; stanza error if an unregistered entity attempts to register too many times before authenticating or if an entity attempts to register a second identity after successfully completing the registration use case; a server MAY also return a &lt;not-authorized/&gt; stream error if the unregistered entity waits too long before authenticating or attempts to complete a task other than authentication after successfully completing the registration use case.</p>
    </section3>
  </section2>
  <section2 topic='Entity Cancels an Existing Registration' anchor='usecases-cancel'>
    <p>The 'jabber:iq:register' namespace also makes it possible for an entity to cancel a registration with a host by sending a &lt;remove/&gt; element in an IQ set. The host MUST determine the identity of the requesting entity based on the 'from' address of the IQ get.</p>
    <example caption='Entity Requests Cancellation of Existing Registration'><![CDATA[
<iq type='set' from='bill@shakespeare.lit/globe' id='unreg1'>
  <query xmlns='jabber:iq:register'>
    <remove/>
  </query>
</iq>
]]></example>
    <example caption='Host Informs Entity of Successful Cancellation'><![CDATA[
<iq type='result' to='bill@shakespeare.lit/globe' id='unreg1'/>
]]></example>
    <p>There are two scenarios:</p>
    <ol>
      <li><p>If the entity cancels its registration with its "home" server (i.e., the server at which it has maintained its XMPP account), then the entity SHOULD NOT include a 'from' or 'to' address in the remove request the server SHOULD then return a &lt;not-authorized/&gt; stream error and terminate all active sessions for the entity. The server SHOULD perform the remove based on the bare JID &LOCALBARE; associated with the current session or connection over which it received the remove request. If the server is an instant messaging and presence server that conforms to &xmppim;, the server SHOULD also cancel all existing presence subscriptions related to that entity (as stored in the entity's roster).</p></li>
      <li><p>If the entity cancels its registration with a service other than its home server, its home server MUST stamp a 'from' address on the remove request, which in accordance with <cite>XMPP Core</cite> will be the entity's full JID &LOCALFULL;. The service MUST perform the remove based on the bare JID &LOCALBARE; portion of the 'from' address.</p></li>
    </ol>
    <p>As specified below, several error cases are possible.</p>
    <table caption='Unregister Error Cases'>
      <tr><th>Condition</th><th>Description</th></tr>
      <tr><td>&badrequest;</td><td>The &lt;remove/&gt; element was not the only child element of the &lt;query/&gt; element.</td></tr>
      <tr><td>&forbidden;</td><td>The sender does not have sufficient permissions to cancel the registration.</td></tr>
      <tr><td>&notallowed;</td><td>No sender is allowed to cancel registrations in-band.</td></tr>
      <tr><td>&registration;</td><td>The entity sending the remove request was not previously registered.</td></tr>
      <tr><td>&unexpected;</td><td>The host is an instant messaging server and the IQ get does not contain a 'from' address because the entity is not registered with the server.</td></tr>
    </table>
    <example caption='Host Informs Client of Failed Cancellation (Bad Request)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
  <error code='400' type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <example caption='Host Informs Client of Failed Cancellation (Forbidden)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
  <error code='401' type='cancel'>
    <forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <example caption='Server Informs Client of Failed Cancellation (Not Allowed)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
  <error code='405' type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <p>A given deployment MAY choose to require additional information (such as the old password or previously-gathered personal information) before cancelling the registration. In order to do so, the server or service SHOULD return a Data Form in the error stanza:</p>
    <example caption='Server Returns Cancellation Form With Error'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='unreg1'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Cancel Registration</title>
      <instructions>Use this form to cancel your registration.</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>jabber:iq:register:cancel</value>
      </field>
      <field type='text-single' label='Username' var='username'>
        <required/>
      </field>
      <field type='text-private' label='Password' var='password'>
        <required/>
      </field>
      <field type='text-single' label='Mother&apos;s Maiden Name' var='x-mmn'>
        <required/>
      </field>
    </x>
  </query>
  <error code='405' type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <p>The user then SHOULD return the form:</p>
    <example caption='User Returns Cancellation Form'><![CDATA[
<iq type='set' from='bill@shakespeare.lit/globe' to='shakespeare.lit' id='unreg2'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='submit'>
      <field type='hidden' var='FORM_TYPE'>
        <value>jabber:iq:register:cancel</value>
      </field>
      <field type='text-single' var='username'>
        <value>bill@shakespeare.lit</value>
      </field>
      <field type='text-private' var='password'>
        <value>theglobe</value>
      </field>
      <field type='text-single' var='x-mmn'>
        <value>Throckmorton</value>
      </field>
    </x>
  </query>
</iq>
]]></example>
  </section2>
  <section2 topic='User Changes Password' anchor='usecases-changepw'>
    <p>The 'jabber:iq:register' namespace enables a user to change his or her password with a server or service. Once registered, the user can change passwords by sending an XML stanza of the following form:</p>
    <example caption='Password Change'><![CDATA[
<iq type='set' to='shakespeare.lit' id='change1'>
  <query xmlns='jabber:iq:register'>
    <username>bill</username>
    <password>newpass</password>
  </query>
</iq>
]]></example>
    <p>Because the password change request contains the password in plain text, a client SHOULD NOT send such a request unless the underlying stream is encrypted (using SSL or TLS) and the client has verified that the server certificate is signed by a trusted certificate authority. A given deployment MAY choose to disable password changes if the stream is not properly encrypted, to disable in-band password changes, or to require additional information (such as the old password or previously-gathered personal information) before changing the password.</p>
    <p>If the user provides an empty password element or a password element that contains no XML character data (i.e., either &lt;password/&gt; or &lt;password&gt;&lt;/password&gt;), the server or service MUST NOT change the password to a null value, but instead MUST maintain the existing password.</p>
    <example caption='Host Informs Client of Successful Password Change'><![CDATA[
<iq type='result' id='change1'/>
]]></example>
    <p>Several error conditions are possible:</p>
    <table caption='Password Change Error Cases'>
      <tr><th>Condition</th><th>Description</th></tr>
      <tr><td>&badrequest;</td><td>The password change request does not contain complete information (e.g., the service requires inclusion of the &lt;username/&gt; element).</td></tr>
      <tr><td>&notauthorized;</td><td>The server or service does not consider the channel safe enough to enable a password change.</td></tr>
      <tr><td>&notallowed;</td><td>The server or service does not allow password changes.</td></tr>
      <tr><td>&unexpected;</td><td>The host is an instant messaging server and the IQ set does not contain a 'from' address because the entity is not registered with the server.</td></tr>
    </table>
    <p>The server or service SHOULD NOT return the original XML sent in IQ error stanzas related to password changes.</p>
    <example caption='Host Informs Client of Failed Password Change (Bad Request)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
  <error code='400' type='modify'>
    <bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <example caption='Host Informs Client of Failed Password Change (Not Authorized)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
  <error code='401' type='modify'>
    <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <example caption='Server Informs Client of Failed Password Change (Not Allowed)'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
  <error code='405' type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <p>In order to require additional information before changing the password, the server or service SHOULD return a Data Form in the error stanza:</p>
    <example caption='Server Returns Password Change Form With Error'><![CDATA[
<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='form'>
      <title>Password Change</title>
      <instructions>Use this form to change your password.</instructions>
      <field type='hidden' var='FORM_TYPE'>
        <value>jabber:iq:register:changepassword</value>
      </field>
      <field type='text-single' label='Username' var='username'>
        <required/>
      </field>
      <field type='text-private' label='Old Password' var='old_password'>
        <required/>
      </field>
      <field type='text-private' label='New Password' var='password'>
        <required/>
      </field>
      <field type='text-single' label='Mother&apos;s Maiden Name' var='x-mmn'>
        <required/>
      </field>
    </x>
  </query>
  <error code='401' type='modify'>
    <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>
]]></example>
    <p>The user then SHOULD return the form:</p>
    <example caption='User Returns Password Change Form'><![CDATA[
<iq type='set' from='bill@shakespeare.lit/globe' to='shakespeare.lit' id='change2'>
  <query xmlns='jabber:iq:register'>
    <x xmlns='jabber:x:data' type='submit'>
      <field type='hidden' var='FORM_TYPE'>
        <value>jabber:iq:register:changepassword</value>
      </field>
      <field type='text-single' var='username'>
        <value>bill@shakespeare.lit</value>
      </field>
      <field type='text-private' var='old_password'>
        <value>theglobe</value>
      </field>
      <field type='text-private' var='password'>
        <value>groundlings</value>
      </field>
      <field type='text-single' var='x-mmn'>
        <value>Throckmorton</value>
      </field>
    </x>
  </query>
</iq>
]]></example>
  </section2>
</section1>
<section1 topic='Extensibility' anchor='extensibility'>
  <p>The fields defined for the 'jabber:iq:register' namespace are strictly limited to those specified in the schema. If a host needs to gather additional information, <cite>XEP-0004: Data Forms</cite> ("x:data") SHOULD be used according to the following rules:</p>
  <ol>
    <li>A host MUST NOT add new fields to the 'jabber:iq:register' namespace; instead, extensibility SHOULD be pursued via the <cite>Data Forms</cite> protocol as specified herein.</li>
    <li>The x:data form shall be contained as a child element of the &lt;query xmlns='jabber:iq:register'/&gt; element (it cannot be a child of the &IQ; stanza and comply with &rfc6120;).</li>
    <li>The x:data form SHOULD contain x:data fields that correspond to all of the iq:register fields (e.g., username and password).</li>
    <li>The x:data form SHOULD use a hidden FORM_TYPE field for the purpose of standardizing field names within the form, as defined in &xep0068;.</li>
    <li>The x:data form shall take precedence over the iq:register fields; if the submitting entity supports the <cite>Data Forms</cite> protocol, it SHOULD submit the data form rather than the predefined 'jabber:iq:register' fields, and MUST NOT submit both the data form and the predefined fields (see the <link url='#precedence'>Precedence Order</link> section of this document).</li>
  </ol>
  <p>Support for extensibility via <cite>Data Forms</cite> is RECOMMENDED but is not required for compliance with this document.</p>
</section1>
<section1 topic='Redirection' anchor='redirect'>
  <p>A given deployment MAY wish to redirect users to another medium (e.g., a website) for registration, rather than allowing in-band registration. The recommended approach is to include only the &lt;instructions/&gt; element rather than the required fields or a data form in the IQ result, as well as a URL encoded using &xep0066; (see the <link url="#precedence">Precedence Order</link> section below for further details).</p>
  <example caption='Host Redirects Entity to Web Registration'><![CDATA[
<iq type='result'
    from='contests.shakespeare.lit'
    to='juliet@capulet.com/balcony'
    id='reg3'>
  <query xmlns='jabber:iq:register'>
    <instructions>
      To register, visit http://www.shakespeare.lit/contests.php
    </instructions>
    <x xmlns='jabber:x:oob'>
      <url>http://www.shakespeare.lit/contests.php</url>
    </x>
  </query>
</iq>
]]></example>
</section1>
<section1 topic='Precedence Order' anchor='precedence'>
  <p>Given the foregoing discussion, it is evident that an entity could receive any combination of iq:register, x:data, and x:oob namespaces from a service in response to a request for information. The precedence order is as follows:</p>
  <ol start='1'>
    <li>x:data</li>
    <li>iq:register</li>
    <li>x:oob</li>
  </ol>
  <p>(Naturally, if the receiving application does not understand any of the foregoing namespaces, it MUST ignore the data qualified by that namespace.)</p>
  <p>Thus it is possible that the host may return any of the following combinations, in which case the submitting application MUST proceed as defined in the table below (it is assumed that "iq:register fields" means instructions plus fields, whereas "iq:register instructions" means the &lt;instructions/&gt; element only):</p>
  <table caption='Recommended Processing of Namespace Combinations'>
    <tr>
      <th>Included Data</th>
      <th>Recommended Processing</th>
      <th>Notes</th>
    </tr>
    <tr>
      <td>iq:register fields</td>
      <td>Submit the completed iq:register fields.</td>
      <td>This is the normal processing model for "legacy" services and clients.</td>
    </tr>
    <tr>
      <td>x:data form + iq:register fields</td>
      <td>Submit the completed x:data form if understood, otherwise submit the completed iq:register fields; however, an application MUST NOT submit both.</td>
      <td>The iq:register fields would be included for "legacy" clients; this combination SHOULD NOT be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields (the next combination SHOULD be used instead).</td>
    </tr>
    <tr>
      <td>x:data form + iq:register instructions</td>
      <td>Submit the completed x:data form if understood, otherwise present the iq:register instructions to the user.</td>
      <td>This combination SHOULD be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields and an alternate URL is not available.</td>
    </tr>
    <tr>
      <td>x:data form + x:oob URL</td>
      <td>Submit the completed x:data form if understood, otherwise present the provided URL as an alternative.</td>
      <td>This combination MAY be returned by a host, but a host SHOULD return the next combination instead in order to support the full range of legacy clients.</td>
    </tr>
    <tr>
      <td>x:data form + iq:register instructions + x:oob URL</td>
      <td>Submit the completed x:data form if understood, otherwise present the iq:register instructions and provided URL as an alternative.</td>
      <td>This combination SHOULD be used if the x:data form includes required fields (e.g., a public key) that are not equivalent to defined iq:register fields and an alternate URL is available.</td>
    </tr>
    <tr>
      <td>iq:register instructions + x:oob URL</td>
      <td>Present the iq:register instructions and provided URL as a redirect.</td>
      <td>This combination MAY be returned by a host that wishes to redirect registration to a URL.</td>
    </tr>
    <tr>
      <td>iq:register fields + x:oob URL</td>
      <td>Submit the completed iq:register fields but optionally present the provided URL as an alternative.</td>
      <td>This combination is NOT RECOMMENDED.</td>
    </tr>
  </table>
</section1>
<section1 topic='Key Element' anchor='key'>
  <p><em>This element is obsolete, but is documented here for historical completeness.</em></p>
  <p>The &lt;key/&gt; element was used as a "transaction key" in certain IQ interactions in order to verify the identity of the sender. In particular, it was used by servers (but generally not services) during in-band registration, since normally a user does not yet have a 'from' address before registering. The flow is as follows:</p>
  <ol>
    <li>Client sends IQ-get request to server.</li>
    <li>Server returns required elements to client, including &lt;key/&gt; element containing a random string (often a SHA-1 hash).</li>
    <li>Client sends registration information to server, including &lt;key/&gt; element with the same value provided by the server.</li>
    <li>Server checks key information and processes registration request; if key is missing or the key value does not match the transaction key provided, the server returns an error.</li>
  </ol>
  <p>The &lt;key/&gt; element was also used during registration removal.</p>
</section1>
<section1 topic='Stream Feature' anchor='streamfeature'>
  <p><cite>RFC 6120</cite> defines methods for advertising feature support during stream negotiation. For the sake of efficiency, it may be desirable for a server to advertise support for in-band registration as a stream feature. The namespace for reporting support within &lt;stream:features/&gt; is "http://jabber.org/features/iq-register". Upon receiving a stream header qualified by the 'jabber:client' namespace, a server returns a stream header to the client and MAY announce support for in-band registration by including the relevant stream feature:</p>
  <example caption='Advertising registration as a stream feature'><![CDATA[
  <stream:features>
    <register xmlns='http://jabber.org/features/iq-register'/>
  </stream:features>
]]></example>
  <p>A server SHOULD NOT advertise in-band registration to another server (i.e., if the initial stream header was qualified by the 'jabber:server' namespace).</p>
</section1>
<section1 topic='Error Handling' anchor='errors'>
  <p>As defined herein, the 'jabber:iq:register' namespace supports both the old (HTTP-style) error codes and the extensible error classes and conditions specified in XMPP Core. A compliant server or service implementation MUST support both old-style and new-style error handling. A compliant client implementation SHOULD support both. For mappings of HTTP-style errors to XMPP-style conditions, refer to &xep0086;.</p>
</section1>
<section1 topic='Determining Support' anchor='disco'>
  <p>If an entity supports the protocol defined herein, it SHOULD report that by including a Service Discovery feature of "jabber:iq:register" in response to disco#info requests.</p>
  <example caption="Service discovery information request"><![CDATA[
<iq from='marlowe.lit'
    id='jzg2d175'
    to='shakespeare.lit'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
  <example caption="Service discovery information response"><![CDATA[
<iq from='shakespeare.lit'
    id='jzg2d175'
    to='marlowe.lit'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    <feature var='jabber:iq:register'/>
  </query>
</iq>
]]></example>
  <p>Although connecting clients typically determine support during stream negotiation via the stream feature, the service discovery feature is helpful for server-to-server connections as well as for clients that are already connected (e.g., to determine if password changes are possible in-band).</p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
  <p>In-band registration is usually not included in other messaging protocols (for example, SMTP does not include a method for registering with an email server), often for reasons of security. The registration methods defined herein are known to be insecure and SHOULD NOT be used unless the channel between the registrant and the entity that accepts registration has been secured. For these reasons, the deployment of in-band registration is a policy matter and a given deployment MAY choose to disable in-band registration and password changes. Furthermore, this document should be deprecated as soon as a successor protocol is defined and implemented.</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
  <p>This document requires no interaction with &IANA;.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
  <section2 topic='Protocol Namespaces' anchor='registrar-ns'>
    <p>The &REGISTRAR; includes the 'jabber:iq:register' namespace in its registry of protocol namespaces.</p>
  </section2>
  <section2 topic='Stream Features' anchor='registrar-stream'>
    <p>The XMPP Registrar includes the 'http://jabber.org/features/iq-register' namespace in its registry of stream feature namespaces.</p>
  </section2>
  <section2 topic='URI Query Types' anchor='registrar-querytypes'>
    <p>As authorized by &xep0147;, the XMPP Registrar maintains a registry of queries and key-value pairs for use in XMPP URIs (see &QUERYTYPES;).</p>
    <p>As described below, the registered querytypes for registration management are "register" and "unregister".</p>
    <section3 topic='register' anchor='registrar-querytypes-register'>
      <p>The 'jabber:iq:register' namespace include a mechanism for creating a registration. The registered querytype for doing so is "register".</p>
      <example caption='Register Action: IRI/URI'><![CDATA[
xmpp:marlowe.shakespeare.lit?register
]]></example>
      <p>Because registration is a two-step process, the application MUST then send an IQ-get to the entity in order to retrieve the required registration fields:</p>
      <example caption='Retrieving Registration Fields'><![CDATA[
<iq to='marlowe.shakespeare.lit' type='get'>
  <query xmlns='jabber:iq:register'/>
</iq>
]]></example>
      <example caption='Receiving Registration Fields'><![CDATA[
<iq from='marlowe.shakespeare.lit' type='result'>
  <query xmlns='jabber:iq:register'>
    <username/>
    <password/>
  </query>
</iq>
]]></example>
      <p>The application MUST then present an appropriate interface that enables the user to complete the registration form. Once the user provides the information, the application MUST send an IQ-set to the entity.</p>
      <example caption='Sending Registration Information'><![CDATA[
<iq to='marlowe.shakespeare.lit' type='set'>
  <query xmlns='jabber:iq:register'>
    <username>juliet</username>
    <password>R0m30</password>
  </query>
</iq>
]]></example>
      <p>The following submission registers the "register" querytype.</p>
      <code><![CDATA[
<querytype>
  <name>register</name>
  <proto>jabber:iq:register</proto>
  <desc>enables registering with a server or service</desc>
  <doc>XEP-0077</doc>
</querytype>
]]></code>
    </section3>
    <section3 topic='unregister' anchor='registrar-querytypes-unregister'>
      <p>The 'jabber:iq:register' namespace include a mechanism for cancelling an existing registration. The registered querytype for doing so is "unregister".</p>
      <example caption='Unregister Action: IRI/URI'><![CDATA[
xmpp:marlowe.shakespeare.lit?unregister
]]></example>
      <example caption='Unregister Action: Resulting Stanza'><![CDATA[
<iq to='marlowe.shakespeare.lit' type='set'>
  <query xmlns='jabber:iq:register'>
    <remove/>
  </query>
</iq>
]]></example>
      <p>The following submission registers the "unregister" querytype.</p>
      <code><![CDATA[
<querytype>
  <name>unregister</name>
  <proto>jabber:iq:register</proto>
  <desc>enables cancellation of a registration with a server or service</desc>
  <doc>XEP-0077</doc>
</querytype>
]]></code>
    </section3>
  </section2>
  <section2 topic='Field Standardization' anchor='registrar-formtypes'>
    <p>There is one FORM_TYPE and set of associated field types and names for field standardization in relation to each major use case for the 'jabber:iq:register' namespace: registration, cancellation of registration, and change of password. The initial submissions for these FORM_TYPES are provided below (additional fields may be provided in future submissions).</p>
    <section3 topic='Registration' anchor='registrar-formtypes-register'>
      <code><![CDATA[
<form_type>
  <name>jabber:iq:register</name>
  <doc>XEP-0077</doc>
  <desc>Standardization of fields related to registration use case.</desc>
  <field
      var='username'
      type='text-single'
      label='Account name associated with the user'/>
  <field
      var='nick'
      type='text-single'
      label='Familiar name of the user'/>
  <field
      var='password'
      type='text-private'
      label='Password or secret for the user'/>
  <field
      var='name'
      type='text-single'
      label='Full name of the user'/>
  <field
      var='first'
      type='text-single'
      label='Given name of the user'/>
  <field
      var='last'
      type='text-single'
      label='Family name of the user'/>
  <field
      var='email'
      type='text-single'
      label='Email address of the user'/>
  <field
      var='address'
      type='text-single'
      label='Street portion of a physical or mailing address'/>
  <field
      var='city'
      type='text-single'
      label='Locality portion of a physical or mailing address'/>
  <field
      var='state'
      type='text-single'
      label='Region portion of a physical or mailing address'/>
  <field
      var='zip'
      type='text-single'
      label='Postal code portion of a physical or mailing address'/>
  <field
      var='phone'
      type='text-single'
      label='Telephone number of the user'/>
  <field
      var='url'
      type='text-single'
      label='URL to web page describing the user'/>
  <field
      var='date'
      type='text-single'
      label='Some date (e.g., birth date, hire date, sign-up date)'/>
  <field
      var='misc'
      type='text-single'
      label='Free-form text field (obsolete)'/>
  <field
      var='text'
      type='text-single'
      label='Free-form text field (obsolete)'/>
  <field
      var='key'
      type='text-single'
      label='Session key for transaction (obsolete)'/>
</form_type>
]]></code>
    </section3>
    <section3 topic='Cancellation' anchor='registrar-formtypes-cancel'>
      <code><![CDATA[
<form_type>
  <name>jabber:iq:register:cancel</name>
  <doc>XEP-0077</doc>
  <desc>Standardization of fields related to cancellation use case.</desc>
  <field
      var='password'
      type='text-private'
      label='Password or secret for the user'/>
  <field
      var='username'
      type='text-single'
      label='Account name associated with the user'/>
</form_type>
]]></code>
    </section3>
    <section3 topic='Change Password' anchor='registrar-formtypes-changepassword'>
      <code><![CDATA[
<form_type>
  <name>jabber:iq:register:changepassword</name>
  <doc>XEP-0077</doc>
  <desc>Standardization of fields related to change password use case.</desc>
  <field
      var='old_password'
      type='text-private'
      label='Old password for the user'/>
  <field
      var='password'
      type='text-private'
      label='Desired password for the user'/>
  <field
      var='username'
      type='text-single'
      label='Account name associated with the user'/>
</form_type>
]]></code>
    </section3>
  </section2>
</section1>
<section1 topic='XML Schemas' anchor='schemas'>
  <section2 topic='jabber:iq:register' anchor='schemas-register'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

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

  <xs:import
      namespace='jabber:x:data'
      schemaLocation='http://www.xmpp.org/schemas/x-data.xsd'/>
  <xs:import
      namespace='jabber:x:oob'
      schemaLocation='http://www.xmpp.org/schemas/x-oob.xsd'/>

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

  <xs:element name='query'>
    <xs:complexType>
      <xs:sequence xmlns:xdata='jabber:x:data'
                   xmlns:xoob='jabber:x:oob'>
        <xs:choice minOccurs='0'>
          <xs:sequence minOccurs='0'>
            <xs:element name='registered' type='empty' minOccurs='0'/>
            <xs:element name='instructions' type='xs:string' minOccurs='0'/>
            <xs:element name='username' type='xs:string' minOccurs='0'/>
            <xs:element name='nick' type='xs:string' minOccurs='0'/>
            <xs:element name='password' type='xs:string' minOccurs='0'/>
            <xs:element name='name' type='xs:string' minOccurs='0'/>
            <xs:element name='first' type='xs:string' minOccurs='0'/>
            <xs:element name='last' type='xs:string' minOccurs='0'/>
            <xs:element name='email' type='xs:string' minOccurs='0'/>
            <xs:element name='address' type='xs:string' minOccurs='0'/>
            <xs:element name='city' type='xs:string' minOccurs='0'/>
            <xs:element name='state' type='xs:string' minOccurs='0'/>
            <xs:element name='zip' type='xs:string' minOccurs='0'/>
            <xs:element name='phone' type='xs:string' minOccurs='0'/>
            <xs:element name='url' type='xs:string' minOccurs='0'/>
            <xs:element name='date' type='xs:string' minOccurs='0'/>
            <xs:element name='misc' type='xs:string' minOccurs='0'/>
            <xs:element name='text' type='xs:string' minOccurs='0'/>
            <xs:element name='key' type='xs:string' minOccurs='0'/>
          </xs:sequence>
          <xs:element name='remove' type='empty' minOccurs='0'/>
        </xs:choice>
        <xs:element ref='xdata:x' minOccurs='0'/>
        <xs:element ref='xoob:x' minOccurs='0'/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>

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

</xs:schema>
]]></code>
  </section2>
  <section2 topic='Stream Feature' anchor='schemas-streams'>
    <code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>

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

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

  <xs:element name='register' type='empty'/>

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

</xs:schema>
]]></code>
  </section2>
</section1>
</xep>