XEP-0077

来自Jabber/XMPP中文翻译计划
2010年5月28日 (五) 04:48Admin (讨论 | 贡献)的版本
跳转到: 导航, 搜索


本文的英文原文来自XEP-0077

XEP-0077:带内注册

摘要: 本文定义了一个XMPP协议扩展用于基于XMPP的即时消息服务器和其他XMPP网络上的服务(例如群聊房间以及和非XMPP的IM服务之间的网关)的带内注册. 本协议可以通过使用数据表单来扩展, 这可以使得服务在注册过程中能够收集广泛的信息. 本协议也支持带内变更密码和取消现有的注册.

作者: Peter Saint-Andre

版权: © 1999 - 2010 XMPP标准化基金会(XSF). 参见法律通告.

状态: 最终

类型: 标准跟踪

版本: 2.3

最后更新日期: 2009-09-15

注意: 这里定义的协议是XMPP标准化基金会的一个最终标准,对于实现和布署来说可以被认为是一个稳定技术.

目录

绪论

Jabber协议很早就包含了一个从即时消息服务器和相关服务进行带内注册的方法. 这个方法使用 'jabber:iq:register' 名字空间并且被广泛记载于Internet-Drafts和其他地方. 因为带内注册不是 RFC 2779 1必需的, 'jabber:iq:register' 名字空间的文档从 XMPP IM 2移除了. 本协议填补了这部分文件的空白.

要求

带内注册必须使一个实体能够向一个主机注册, 从一个主机取消现有的注册, 或从一个主机变更密码. 这里"host"的含义如下:

  1. 一个即时消息服务器, 如 XMPP IM 中所描述并且在 服务发现 [[XEP-0077#附录G:备注|3] 中的 category+type 标识为 "server/im"
  2. 一个附加的服务, 例如一个网关(见 网关互动 4) 或一个多用户聊天 5服务

如果必要, 关于信息收集的扩展性应该使用 数据表单 6.

用例

实体注册到一个主机

为了确定向一个主机注册需要哪些字段, 一个实体应该(SHOULD)首先发送一个 IQ get 给主机. 这个实体不应该(SHOULD NOT)通过先发送一个IQ set来尝试猜测需要的字段 , 因为需要的数据的性质是由服务决定的.

例子 1. 实体向主机请求注册字段

<iq type='get' id='reg1'>
  <query xmlns='jabber:iq:register'/>
</iq>

如果实体未曾注册并且主机支持带内注册, 主机必须(MUST)通知实体需要的注册字段. 如果主机不支持带内注册, 它必须(MUST)返回一个 <service-unavailable/> 错误. 如果一个主机重定向注册请求到一些其他的媒介(例如web网站), 它只可以(MAY)返回一个 <instructions/> 元素, 详见本文的 重定向 章节.

例子 2. 主机返回注册字段给实体

<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>

如果主机确定(基于'from'地址) 该实体已经注册, 它给该IQ get返回的应答IQ result中必须(MUST)包含一个空的<registered/>元素(表示该实体已注册), 应该(SHOULD)包含该实体当前已有的注册信息(尽管<password/>元素可以(MAY)是空的), 并且应该(SHOULD)包含一个<instructions/>元素(其XML字符数据可以(MAY)被修改以反映该实体已被注册的事实).

如果该主机是一个即时消息服务器, 在这个阶段它应该(SHOULD)假设请求的实体是未注册的,除非实体已经被验证(详见下文中的 注册到一个服务器 章节).

例子 3. 主机通知实体当前的注册

<iq type='result' id='reg1'>
  <query xmlns='jabber:iq:register'>
    <registered/>
    <username>juliet</username>
    <password>R0m30</password>
    <email>juliet@capulet.com</email>
  </query>
</iq>

如果实体还未注册, 该实体应该(SHOULD)提供必需的信息.

例子 4. 实体提供必需信息

<iq type='set' id='reg2'>
  <query xmlns='jabber:iq:register'>
    <username>bill</username>
    <password>Calliope</password>
    <email>bard@shakespeare.lit</email>
  </query>
</iq>

注意: 请求的实体必须(MUST)在IQ result中包含提供的所有元素信息(不只是<instructions/>元素).

例子 5. 主机通知实体注册成功

<iq type='result' id='reg2'/>

反之, 注册可能失败. 可能的失败包括用户名冲突(期待的用户名已经被另一个实体使用)以及请求的实体未能提供完全的必需信息.

例子 6. 主机通知实体注册失败(用户名冲突)

<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>

如果请求的实体在注册时未提供所有的请求信息 7, 那么服务器或者服务必须(MUST)返回一个<not-acceptable/>错误给请求实体.

例子 7. 主机通知实体注册失败(一些必需的信息未提供)

<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>

如果主机需要超出以上的以及超过schema定义的数据元素的额外信息, 它应该(SHOULD)使用本文的 可扩展性 章节里描述的数据表单. (下面三个例子展示一个现有的账号注册到一个第三方服务, 而不是一个实体向一个服务器注册账号)


例子 8. 实体向主机请求注册字段

<iq type='get'
    from='juliet@capulet.com/balcony'
    to='contests.shakespeare.lit'
    id='reg3'>
  <query xmlns='jabber:iq:register'/>
</iq>

例子 9. 主机返回注册表单给实体

<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>

然后用户应该(SHOULD)返回表单:

例子 10. 用户提交注册表单

<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>

注册到一个服务器

当一个未注册的实体和一个服务器而不是一个服务交互时必须特别注意. 通常, 一个服务器允许带内注册以使实体能够在Jabber网络里面自举"bootstrap"参与; 这个 bootstrapping 发生了一个未注册以及未验证的实体向一个服务器打开一个TCP连接并立刻完成该服务器的注册用例的时候, 然后使用这个全新注册的标识进行验证. 如上所述, 当一个服务器收到一个 IQ-get 用于注册信息, 它应该(SHOULD)假设请求实体是未注册的除非该实体已经验证.

取决于本地服务的供应, 如果一个未注册的实体在验证之前尝试太多次数的注册,或者一个实体成功完成注册用例之后尝试注册第二个身份,那么一个服务器可以(MAY)返回一个<not-acceptable/>节错误; 如果未注册的实体在验证之前等待太久或者在成功完成注册用例之后尝试完成一个动作而这个动作不是在做验证, 一个服务器也可以(MAY)返回一个<not-authorized/>流错误.

实体取消现存注册

'jabber:iq:register'名字空间允许一个实体也能够从一个主机取消一个注册, 通过发送一个包含<remove/>元素的 IQ set. 该主机必须(MUST)根据 IQ get 的 'from' 地址来确定请求实体的身份.

例子 11. 实体请求注销现存注册

<iq type='set' from='bill@shakespeare.lit/globe' id='unreg1'>
  <query xmlns='jabber:iq:register'>
    <remove/>
  </query>
</iq>

例子 12. 主机通知实体成功注销

<iq type='result' to='bill@shakespeare.lit/globe' id='unreg1'/>

有两种情形:

  1. 如果实体从他的"home"服务器取消注册(也就是说,维护它的XMPP帐号的服务器), 那么该实体不应该(SHOULD NOT)包含一个 'from' 或 'to' 地址在移除请求中, 该服务器应该(SHOULD)返回一个<not-authorized/>流错误并且终止该实体所有激活的会话. 该服务器应该(SHOULD)执行的移除操作以其收到移除请求的当前会话或连接的相关的纯JID (<node@domain.tld>)为准. 如果服务器是一个即时消息和出席信息服务期并遵循 RFC 3921 8, 该服务器也应该(SHOULD)取消所有和该实体相关的现存的出席信息订阅(储存在实体的花名册中).
  2. 如果实体从一个服务而不是它的宿主服务器取消注册, 它的宿主服务器必须(MUST)贴一个'from'地址到移除请求中, 这个遵循 XMPP Core 的地址应为该实体的全 JID (<node@domain.tld/resource>). 该服务必须(MUST)基于'from'地址的纯JID (<node@domain.tld>)部分来执行移除操作.

如下所述, 各种错误可能发生.

表 1: 注销出错例子

条件 描述
<bad-request/> <remove/> 元素不只是<query/> 元素的唯一子元素.
<forbidden/> 发送者没有足够的权限取消注册.
<not-allowed/> 没有发送者被允许在带内取消注册.
<registration-required/> 发送移除请求的实体未曾注册.
<unexpected-request/> 主机是一个即时消息服务器而 IQ get 不包含一个 'from' 地址, 因为该实体不是注册到该服务器.

例子 13. 主机通知客户端注销失败(错误的请求)

<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>

例子 14. 主机通知客户端注销失败(禁止)

<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>

例子 15. 主机通知客户端注销失败(不允许)

<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>

一个给定的布署可以(MAY)选择在取消注册之前要求额外的信息(例如旧密码或以前收集的个人信息). 为了做到这一点, 服务器或服务应该(SHOULD)在错误节里面返回一个数据表单:

例子16. 服务器在错误信息中返回注销表单

<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>Password Change</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>

然后用户应该(SHOULD)返回表单:

例子 17. 用户返回注销表单

<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>

用户变更密码

'jabber:iq:register'名字空间允许用户从一个服务器或服务变更其密码. 一旦注册了之后, 该用户可以通过发送一个以下格式的XML节来变更密码:

例子 18. 密码变更

<iq type='set' to='shakespeare.lit' id='change1'>
  <query xmlns='jabber:iq:register'>
    <username>bill</username>
    <password>newpass</password>
  </query>
</iq>

因为密码变更请求包含了一个纯文本的密码, 一个客户端不应该(SHOULD NOT)发送这样一个请求除非所在的流是加密的(使用 SSL 或 TLS) 并且客户端已经确保该服务器的证书是由一个可信任的机构验证的. 一个给定的布署可以(MAY)选择禁止密码变更, 如果流不是加密的, 禁止带内密码变更或在变更密码之前要求额外的信息(类似旧密码或者以前收集的个人信息).

如果用户提供一个空的密码元素或一个不包含XML字符数据的密码元素(也就是说, <password/> 或<password></password>), 服务器或服务不能(MUST NOT)变更密码到一个空值, 而必须(MUST)维持现有的密码.

例子 19. 主机通知客户端成功变更密码

<iq type='result' id='change1'/>

可能发生的一些错误:

表 2: 密码变更出错例子

条件 描述
<bad-request/> 密码变更请求未包含完整的信息(例如, 服务要求包含<username/>元素).
<not-authorized/> 服务器或服务不能确定通道对于密码变更足够安全.
<not-allowed/> 服务器或服务部允许密码变更.
<unexpected-request/> 主机是一个即时消息服务器并且 IQ set 不包含一个'from'地址,因为该实体未曾注册到这台服务器.

服务器或服务在返回的IQ错误节中不应该(SHOULD NOT)包含和密码变更相关的原始的XML.

例子 20. 主机通知客户端密码变更失败(错误的请求)

<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>

例子 21. 主机通知客户端密码变更失败(未授权)

<iq type='error' from='shakespeare.lit' to='bill@shakespeare.lit/globe' id='change1'>
  <error code='401' type='cancel'>
    <not-authorized xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

例子 22. 主机通知客户端密码变更失败(不允许)

<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>

为了在变更密码之前要求额外的信息, 服务器或服务应该(SHOULD)在错误节中返回一个数据表单:

例子 23. 服务器在错误中返回密码变更表单

<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='405' type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
  </error>
</iq>

用户应该(SHOULD)返回表单:

例子 24. 用户返回密码变更表单

<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>

可扩展性

为 'jabber:iq:register' 名字空间定义的字段严格受限于那个schema. 如果一个主机需要收集额外的信息, XEP-0004: Data Forms ("x:data") 应该(SHOULD)遵循以下规则:

  1. 一个主机不能(MUST NOT)增加新的字段给 'jabber:iq:register' 名字空间; 而是, 可扩展性应该(SHOULD)通过这里指定的数据表单协议来达到.
  2. x:data 表单将作为一个子元素被包含在 <query xmlns='jabber:iq:register'/> 元素中(它不能是一个 <iq/> 节的子元素 并且遵守 RFC 3920 9 的 9.2.3 章节).
  3. x:data 表单应该(SHOULD)包含 x:data 字段以对应所有 iq:register 字段 (例如, 用户名和密码).
  4. x:data 表单应该(SHOULD)使用一个隐含的 FORM_TYPE 字段用于表单的字段标准化, 如 数据表单的字段标准化 10章节所定义的那样.
  5. x:data 表单将优先处理 iq:register 字段; 如果提交的实体支持 数据表单 协议, 它应该(SHOULD)提交这个数据表单而不是预定义的 'jabber:iq:register' 字段, 并且不能(MUST NOT)同时提交数据表单和预定义字段(见本文的 优先次序 章节).

通过 数据表单 对扩展性的支持是推荐的(RECOMMENDED), 但不是兼容本文所必需的.

重定向

一个给定的部署可能(MAY)希望重定向用户到另一个媒介(例如web网站) 去注册, 而不是允许带内注册. 推荐的方法是只包含一个 <instructions/> 元素而不是必需的字段或数据表单到 IQ result, 也就是一个采用 带外数据 11编码的URL(详见下文的 优先次序 章节).

例子 25. 主机重定向实体到web注册

<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>

优先次序

基于前述的讨论, 可见一个实体从一个服务对其请求信息的应答所接收的可以是 iq:register, x:data, 以及 x:oob 名字空间的任意组合. 其优先次序如下:

  1. x:data
  2. iq:register
  3. x:oob

(自然, 如果接收的应用不理解任何前述的名字空间, 它必须(MUST)忽略被这些名字空间所限定的数据.)

从而一个主机有可能返回任何以下的组合, 在哪种情况下提交的应用必须(MUST)进行下表定义的操作(假设"iq:register fields" 表示 instructions 加 字段, 而 "iq:register instructions" 只表示 <instructions/> 元素):

表 3: 推荐的名字空间组合的处理

包含的数据 推荐的处理 备注
iq:register fields 提交完整的 iq:register 字段. 这是通用的处理模式用于"遗留"服务和客户端.
x:data form + iq:register fields 如果理解, 提交完整的 x:data 表单, 否则提交完整的 iq:register 字段; 无论如何, 一个应用不能(MUST NOT)同时提交两者. iq:register 字段将被用于"遗留"客户端; 如果 x:data 表单包含必需的字段(例如, 一个public key)并且这字段不同于已定义的 iq:register 字段, 这个组合不应该被(SHOULD NOT)使用, 而应该(SHOULD)使用下一个组合.
x:data form + iq:register instructions 如果理解, 提交完整的 x:data 表单, 否则展示 iq:register instructions 给用户. 如果 x:data 表单包含必需的字段(例如 一个 public key)而这字段不同于已定义的 iq:register 字段并且没有替代的URL可用, 这个组合应该(SHOULD)使用.
x:data form + x:oob URL 如果理解,提交完整的 x:data 表单, 否则提供替代的URL给用户 . 本组合可以(MAY)由一个主机返回, 但是一个主机应该(SHOULD)返回下一个组合以支持全范围的遗留客户端.
x:data form + iq:register instructions + x:oob URL 如果理解,提交完整的 x:data 表单, 否则展示 iq:register instructions 并提供替代的URL给用户. 如果 x:data 表单包含必需的字段(例如, 一个 public key)而这个字段不同于已定义的 iq:register 字段并且没有替代的URL可用, 本组合应该(SHOULD)使用.
iq:register instructions + x:oob URL 展示 iq:register instructions 和提供的重定向URL. 本组合可以(MAY)由一个希望重定向注册到一个URL的主机返回.
iq:register fields + x:oob URL 提交完整的 iq:register 字段但是可选的展示替代的URL. 本组合不推荐(NOT RECOMMENDED).

Key元素

这个元素已过时了, 但是纪录下来以保持历史的完整性.

<key/>元素是在建立 IQ 交互时用的一个 "transaction key" , 为了验证发送者的身份. 典型的, 它被用于进行带内注册时的服务器 (但通常不是服务), 因为通常一个用户在注册之前还没有一个'from'地址. 流程如下:

  1. 客户端发送 IQ-get 请求给服务器.
  2. 服务器返回必需的元素给客户端, 包含 <key/> 元素,其值为一个随机的字符串 (经常是一个 SHA-1 哈希值).
  3. 客户端发送注册信息给服务器, 其中包含 <key/> 元素, 其值和服务器提供的一致.
  4. 服务器检查 key 信息并且处理注册请求; 如果没有 key 或 key 值和提供的transaction key值不一致, 服务器返回一个错误.

<key/>元素也被用于注册取消过程中.

流特性

RFC 3920 定义了流协商时声明支持的特性的方法. 为了追求效率, 它可能期望一个服务器把支持带内注册作为一个流特性来声明. 用于汇报支持的<stream:features/>名字空间是"http://jabber.org/features/iq-register". 在接收一个由'jabber:client'名字空间限定的流头信息之后, 一个服务器返回一个流头信息给该客户端, 并且可以(MAY)声明对带内注册的支持(即包含有关的流特性):

例子 26. 声明注册为一个流特性

<?xml version='1.0' encoding='utf-8'?>
<stream:stream xmlns:stream='http://etherx.jabber.org/streams/'
    xmlns='jabber:client'
    from='somedomain'
    version='1.0'>
  <stream:features>
    ...
    <register xmlns='http://jabber.org/features/iq-register'/>
    ...
  </stream:features>

一个服务器不应该(SHOULD NOT)向另一个服务器(也就是说, 如果初始化流头信息是由'jabber:server'名字空间限定的)声明带内注册.

错误处理

如此处所定义的, 'jabber:iq:register'名字空间同时支持老的 (HTTP-style) 错误码和定义在 XMPP Core 中的可扩展的错误级别及条件. 一个兼容的服务器或服务实现必须(MUST)同时支持老格式和新格式的错误处理. 一个兼容的客户端实现应该(SHOULD)支持两者. 关于 HTTP-style 错误对应XMPP-style 条件的映射表, 参考 错误条件映射 12.

安全事项

带内注册经常不包含在其他消息协议中(例如, SMTP不包含一个方法用于向一个email服务器注册), 经常是因为安全的原因. 这里定义的注册方法据知是不安全的并且不应该(SHOULD NOT)使用, 除非注册方和接受注册的实体之间的通道是安全的. 因为这些原因, 带内注册的布署是一个策略问题并且一个给定的布署可以(MAY)选择禁止带内注册和密码变更. 此外, 一旦一个成功的协议被定义和实现, 本文应该立刻过时.

IANA事项

本文档与互联网编号分配授权机构 13无关。

XMPP注册事项

协议名字空间

XMPP注册员XMPP Registrar 14在它的协议名字空间注册项中包含了 'jabber:iq:register' 名字空间.

流特性

XMPP注册员 XMPP Registrar在它的流特性名字空间的注册项中包括了'http://jabber.org/features/iq-register' 名字空间.

URI查询类型

作为由XMPP URI Query Components 15授权的机构, XMPP登记处维护着一个用于 XMPP URIs 的查询和键-值对的注册项(见<http://www.xmpp.org/registrar/querytypes.html>)。

如下所述, 已注册的用于注册管理的查询类型为 "register" 和 "unregister".

register

"jabber:iq:register"名字空间包含了一个新建注册的机制. 完成这项工作的已注册的查询类型为"register".

例子 27. 注册动作: IRI/URI

xmpp:marlowe.shakespeare.lit?register

因为注册是一个两步的过程, 应用程序必须(MUST)接着发送一个 IQ-get 给实体让其接收必需的注册字段:

例子 28. 接收注册字段

<iq to='marlowe.shakespeare.lit' type='get'>
  <query xmlns='jabber:iq:register'/>
</iq>

例子 29. 接收注册字段

<iq from='marlowe.shakespeare.lit' type='result'>
  <query xmlns='jabber:iq:register'>
    <username/>
    <password/>
  </query>
</iq>

应用程序必须(MUST)接着展示一个适当的界面使用户能够完成注册表单. 一旦用户提供了信息, 应用程序必须(MUST)发送一个 IQ-set 给实体.

例子 30. 发送注册信息

<iq to='marlowe.shakespeare.lit' type='set'>
  <query xmlns='jabber:iq:register'>
    <username>juliet</username>
    <password>R0m30</password>
  </query>
</iq>

以下提交注册了 "register" 查询类型.

<querytype>
  <name>register</name>
  <proto>jabber:iq:register</proto>
  <desc>enables registering with a server or service</desc>
  <doc>XEP-0077</doc>
</querytype>

unregister

'jabber:iq:register'名字空间包含了一个取消现有注册的机制. 完成这个工作的已注册的查询类型为"unregister".

例子 31. 取消注册动作: IRI/URI

xmpp:marlowe.shakespeare.lit?unregister

例子 32. 取消注册动作: 结果节

<iq to='marlowe.shakespeare.lit' type='get'>
  <query xmlns='jabber:iq:register'>
    <remove/>
  </query>
</iq>

以下提交注册了"unregister"查询类型.

<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>

字段标准化

对于每个和 'jabber:iq:register' 名字空间有关的主要用例的字段标准化,有一个 FORM_TYPE 以及相关的字段类型和字段名称: 注册, 取消注册, 变更密码. 这些 FORM_TYPES 的初始提交如下(另外的字段可以由将来的提交提供).

注册

<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='First name or given name of the user'/>
  <field
      var='last'
      type='text-single'
      label='Last name, surname, or 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>

注销

<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>

变更密码

<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>

XML架构

jabber:iq:register

<?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>

Stream Feature

<?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>

附录

附录A:文档信息

系列:XEP

序号:0077

发布者:XMPP标准基金会

状态:终结版

类型:标准跟踪

版本:2.3

最后更新:2009-09-15

批准机构:XMPP理事会

依赖标准:XMPP Core

替代标准:无

被替代标准:无

缩略名:iq-register

XML架构: <http://www.xmpp.org/schemas/iq-register.xsd>

原文控制: HTML RSS

本文的其它格式: XML PDF

附录B:作者信息

Peter Saint-Andre

Email: stpeter@jabber.org

JabberID: stpeter@jabber.org

URI: https://stpeter.im/

附录C:法律通告

模板:XEP法律通告

附录D:和XMPP的关系

可扩展的消息和出席信息协议 (XMPP) 定义于 XMPP Core (RFC 3920) 和 XMPP IM (RFC 3921) 规范里,由 XMPP标准基金会贡献到由依据RFC 2026成立的互联网工程人物组管理的互联网标准流程 Internet Standards Process. 本文定义的任何协议已在互联网标准流程之外开发,并且被理解为 XMPP 的扩展而不是一个XMPP本身的演化, 开发, 或修改.

附录E:讨论地点

主要的XMPP扩展协议讨论地点是 <standards@xmpp.org> 讨论列表.

在 xmpp.org 的其它讨论列表中的讨论可能也有合适的; 所有的列表见 <http://xmpp.org/about/discuss.shtml> .

勘误表可以发送邮件到 <editor@xmpp.org>.

附录F:需求一致性

以下用于本文的需求关键字的解释见于 RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".

附录G:备注

  1. RFC 2779: A Model for Presence and Instant Messaging <http://tools.ietf.org/html/rfc2779>.
  2. RFC 3921: 可扩展的消息和出席信息协议 (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.
  3. XEP-0030: Service Discovery <http://www.xmpp.org/extensions/xep-0030.html>.
  4. XEP-0100: Gateway Interaction <http://www.xmpp.org/extensions/xep-0100.html>.
  5. XEP-0045: Multi-User Chat <http://www.xmpp.org/extensions/xep-0045.html>.
  6. XEP-0004: Data Forms <http://www.xmpp.org/extensions/xep-0004.html>.
  7. 这包括提供一个空的 password 元素或一个不包含XML字符数据的 password 元素 , 即, 要么是 <password/> 要么是 <password></password>.
  8. RFC 3921: 可扩展的消息和出席信息协议 (XMPP): Instant Messaging and Presence <http://tools.ietf.org/html/rfc3921>.
  9. RFC 3920: 可扩展的消息和出席信息协议 (XMPP): Core <http://tools.ietf.org/html/rfc3920>.
  10. XEP-0068: Field Data Standardization for Data Forms <http://www.xmpp.org/extensions/xep-0068.html>.
  11. XEP-0066: Out of Band Data <http://www.xmpp.org/extensions/xep-0066.html>.
  12. XEP-0086: Error Condition Mappings <http://www.xmpp.org/extensions/xep-0086.html>.
  13. 互联网编号分配机构(IANA) 是用于互联网协议的唯一性参数值分配的核心协调者, 例如号码和URI计划. 更多信息, 见 <http://www.iana.org/>.
  14. XMPP登记员XMPP Registrar 维护着一个保留的协议名字空间以及用于由XMPP标准基金会批准的XMPP扩展协议的上下文参数的注册项的列表. 更多信息, 见 <http://xmpp.org/registrar/>.
  15. XEP-0147: XMPP URI Query Components <http://www.xmpp.org/extensions/xep-0147.html>.

附录H:修订历史

注意: 本协议的旧版本可能在 http://xmpp.org/extensions/attic/ 还可用

版本 2.3 (2009-09-15)

澄清字段 "first" 和 "last" 实际上总是分别用于显示名 given name 和姓 family name.

(psa)

版本 2.2 (2006-01-24)

进一步定义了和数据表单的集成, 特别是如果需要在注销现有用户时要求额外的信息 (例如, 用户名和密码) 或更改密码 (例如, 旧密码); 也澄清了注销注册时服务器的处理.

(psa)

版本 2.1 (2005-07-14)

澄清了可扩展性规则; 移除了过期时间expiration date; 修改了架构 schema 以列入 jabber:x:data 和 jabber:x:oob 信息的可选包含项.

(psa)

版本 2.0 (2004-08-30)

通过Jabber理事会的投票, 提升状态为最终版Final; 也定义了服务器server的含义就是一个即时消息服务器.

(psa)

版本 1.6 (2004-08-23)

为了引起理事会的关注, 澄清了 x:data, iq:register, 和 x:oob 的优先次序; 进一步定义了未注册实体初始注册请求时服务器的处理.

(psa)

版本 1.5 (2004-07-21)

指定服务器对于来自未注册实体的请求的处理.

(psa)

版本 1.4 (2004-05-10)

移除关于服务器和服务的一致性语言 (属于一套协议规范).

(psa)

Version 1.3 (2004-02-24)

Added text about redirection to web registration.

(psa)

Version 1.2 (2003-11-26)

Documented use of <key/> element; added optional stream feature; added XMPP error handling; specified handling of empty passwords.

(psa)

Version 1.1 (2003-10-02)

Moved change password use case from XEP-0078.

(psa)

Version 1.0 (2003-06-18)

Per a vote of the Jabber Council, advanced status to Draft.

(psa)

Version 0.9 (2003-06-18)

Changes to address Council concerns.

(psa)

Version 0.8 (2003-06-13)

Restored the <misc/> and <text/> elements; added the old <key/> element; specified these three elements as obsolete.

(psa)

Version 0.7 (2003-06-12)

Added <registered/> element; specified FORM_TYPE for x:data form; clarified that support for the extensibility mechanism is optional; removed the <misc/> and <text/> elements (not necessary given extensibility option); added <nick/>, <first/>, and <last/> elements that were traditionally documented as part of jabber:iq:register.

(psa)

Version 0.6 (2003-06-06)

Removed XMPP-style error conditions until formats are stable.

(psa)

Version 0.5 (2003-05-30)

Removed "encrypted secret" content, added information about expiration date.

(psa)

Version 0.4 (2003-05-28)

Added "encrypted secret" content.

(psa)

Version 0.3 (2003-05-20)

Slight editorial revisions.

(psa)

Version 0.2 (2003-04-29)

Fixed schema, made minor editorial changes.

(psa)

Version 0.1 (2003-04-06)

Initial version.

(psa)


结束

个人工具