mirror of
https://github.com/moparisthebest/xeps
synced 2024-12-21 15:18:51 -05:00
XEP-0389: overhaul document structure
This also adds more information to the <success> element to make flows where the server assigns the JID possible.
This commit is contained in:
Sam Whited
parent
a8b67624ac
commit
ae5f2c7ade
284
xep-0389.xml
284
xep-0389.xml
@ -31,6 +31,19 @@
|
||||
<supersededby/>
|
||||
<shortname>ibr2</shortname>
|
||||
&sam;
|
||||
<revision>
|
||||
<version>0.5.0</version>
|
||||
<date>2020-05-26</date>
|
||||
<initials>ssw</initials>
|
||||
<remark>
|
||||
<ul>
|
||||
<li>Overhaul document for readability.</li>
|
||||
<li>Add JID and username information to success element.</li>
|
||||
<li>Always require disco/caps feature.</li>
|
||||
<li>More examples.</li>
|
||||
</ul>
|
||||
</remark>
|
||||
</revision>
|
||||
<revision>
|
||||
<version>0.4.0</version>
|
||||
<date>2020-04-22</date>
|
||||
@ -209,7 +222,7 @@
|
||||
…
|
||||
</query>]]></example>
|
||||
</section1>
|
||||
<section1 topic='Registration Flows' anchor='flows'>
|
||||
<section1 topic='Flows' anchor='flows'>
|
||||
<p>
|
||||
Registration or recovery is completed after responding to a series of
|
||||
challenges issued by the server.
|
||||
@ -223,15 +236,16 @@
|
||||
<section2 topic='Stream Feature'>
|
||||
<p>
|
||||
If a server supports registering for or recovering an account using
|
||||
Extensible IBR, it MUST inform the connecting client when returning stream
|
||||
features during the stream negotiation process.
|
||||
Extensible IBR during stream negotiation, it MUST inform the connecting
|
||||
client when returning stream features during the stream negotiation process.
|
||||
This is done by including a <register/> element, qualified by the
|
||||
'urn:xmpp:register:0' namespace for account registration, or a
|
||||
<recovery/> element qualified by the same namespace for account
|
||||
recovery.
|
||||
The register and recovery features are always voluntary-to-negotiate.
|
||||
The registration and recovery features MUST NOT be advertised before
|
||||
encryption has been negotiated, eg. using direct TLS or opportunistic TLS.
|
||||
The registration and recovery features MUST NOT be advertised before a
|
||||
security layer has been negotiated, eg. using direct TLS or opportunistic
|
||||
TLS.
|
||||
They SHOULD be advertised at the same time as the SASL authentication
|
||||
feature, meaning that after registration or recovery is completed SASL
|
||||
authentication can proceed.
|
||||
@ -244,15 +258,17 @@
|
||||
workflow that only contains challenges which the client supports.
|
||||
Each <flow/> element MUST have a unique "id" attribute which is used
|
||||
by the client to identify the flow being selected.
|
||||
They must also have at least one <name/> element containing a short,
|
||||
The id attribute is only used during this particular flow negotiation and
|
||||
has no meaning after a flow has been selected.
|
||||
Flows must also have at least one <name/> element containing a short,
|
||||
human readable description of the flow.
|
||||
If multiple <name/> elements are present they MUST have unique values
|
||||
for the "xml:lang" attribute.
|
||||
Clients MAY use the name element to show the different flows to the user and
|
||||
ask them to pick between them.
|
||||
Each flow must also contain an unordered set of <challenge/> elements
|
||||
representing the various challenges that must be completed to complete the
|
||||
registration or recovery flow.
|
||||
Each flow element must also contain an unordered set of <challenge/>
|
||||
elements representing the various challenge types that may be required to
|
||||
complete the registration or recovery flow.
|
||||
Each <challenge/> element contains a "type" attribute that uniquely
|
||||
identifies the challenge for the purpose of determining if it is supported.
|
||||
If a flow would offer the same challenge twice (eg. two data forms asking
|
||||
@ -296,7 +312,18 @@
|
||||
</recovery>
|
||||
</stream:features>]]></example>
|
||||
</section2>
|
||||
<p>
|
||||
Just because a challenge type is listed by the server in the initial flow
|
||||
element does not mean that it will be issued by the server.
|
||||
Servers MAY choose to issue more or fewer challenges based on the result of
|
||||
previous challenges and may not use every challenge type listed in the
|
||||
original flow.
|
||||
</p>
|
||||
<section2 topic='Retrieving the Flows'>
|
||||
<p>
|
||||
Registration or recovery may also be completed after stream neogtiation if
|
||||
server policy allows it.
|
||||
</p>
|
||||
<p>
|
||||
To find what flows an entity provides (if any) after stream negotiation is
|
||||
complete the requester can send an IQ of type "get" containing a
|
||||
@ -309,7 +336,7 @@
|
||||
</iq>]]></example>
|
||||
<p>
|
||||
When responding to a query for registration or recovery flows the list of
|
||||
challenges should be included just as it would be if during stream feature
|
||||
challenges MUST be included just as it would be during stream feature
|
||||
negotiation.
|
||||
That is, a "register" or "recovery" element containing a list of flows,
|
||||
each with an id, containing a name and a list of challenges.
|
||||
@ -333,67 +360,140 @@
|
||||
</register>
|
||||
</iq>]]></example>
|
||||
<p>
|
||||
If an entity supports this specification but does not provide any flows
|
||||
after stream negotiation it MUST respond with an empty list.
|
||||
If an entity supports issuing challenges but does not provide any flows
|
||||
after stream negotiation is complete it MUST respond with an empty list.
|
||||
Similarly, an entity that supports this specification but does not support
|
||||
issuign challenges itself (for example, a client that only supports
|
||||
receiving challenges) it MUST respond successfully with an empty list.
|
||||
</p>
|
||||
<example caption='Empty registration flows results'><![CDATA[
|
||||
<iq type='result'>
|
||||
<register xmlns='urn:xmpp:register:0'/>
|
||||
</iq>]]></example>
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Challenges' anchor='challenge'>
|
||||
<p>
|
||||
A client selects the registration or recovery feature for negotiation by
|
||||
replying with an element of the same name and namespace.
|
||||
The element MUST contain a <flow> element that MUST have an "id"
|
||||
attribute matching one of the flows advertised by the server.
|
||||
For example, to select the "Verify by Phone Call" registration flow from
|
||||
the previous example, the client would reply with:
|
||||
</p>
|
||||
<section2 topic='Issuing Challenges' anchor='challenge'>
|
||||
<p>
|
||||
A client selects the registration or recovery feature for negotiation by
|
||||
replying with an element of the same name and namespace.
|
||||
The element MUST contain a <flow> element that MUST have an "id"
|
||||
attribute matching one of the flows advertised by the server.
|
||||
For example, to select the "Verify by Phone Call" registration flow from
|
||||
the previous example, the client would reply with:
|
||||
</p>
|
||||
<example caption='Client selects a recovery flow'><![CDATA[
|
||||
<register xmlns='urn:xmpp:register:0'>
|
||||
<flow id='1'/>
|
||||
</register>]]></example>
|
||||
<p>
|
||||
If the client is initiating registration or recovery after a stream has
|
||||
already been initiated it uses the same registration element wrapped in an
|
||||
IQ of type "set".
|
||||
<p>
|
||||
If the client is initiating registration or recovery after a stream has
|
||||
already been initiated it uses the same registration element wrapped in an
|
||||
IQ of type "set".
|
||||
</p>
|
||||
<example caption='Client selects a recovery flow after stream negotiation'><![CDATA[
|
||||
<example caption='Client selects a recovery flow after stream negotiation'><![CDATA[
|
||||
<iq type='set' id='foo'>
|
||||
<recovery xmlns='urn:xmpp:register:0'>
|
||||
<flow id='0'/>
|
||||
</recovery>
|
||||
</iq>]]></example>
|
||||
<p>
|
||||
The server then replies to the IQ or feature selection with a challenge.
|
||||
If replying to an IQ, the challenge must be wrapped in an IQ of type
|
||||
"result".
|
||||
Challenges take the form of a <challenge/> element qualified by the
|
||||
'urn:xmpp:register:0' namespace with a 'type' attribute that uniquely
|
||||
identifies the type of payload a client might expect the element to contain.
|
||||
</p>
|
||||
<p>
|
||||
The server then replies to the IQ or feature selection with a challenge.
|
||||
If replying to an IQ, the challenge must be wrapped in an IQ of type
|
||||
"result".
|
||||
Challenges take the form of a <challenge/> element qualified by the
|
||||
'urn:xmpp:register:0' namespace with a 'type' attribute that uniquely
|
||||
identifies the type of payload a client might expect the element to
|
||||
contain.
|
||||
</p>
|
||||
<example caption='Server issues a challenge'><![CDATA[
|
||||
<challenge xmlns='urn:xmpp:register:0'
|
||||
type='urn:example:challenge'>
|
||||
<example xmlns='urn:example:challenge'>Payload</example>
|
||||
</challenge>]]></example>
|
||||
<p>
|
||||
After a challenge is received, the client replies to the challenge by
|
||||
sending a <response/> element qualified by the 'urn:xmpp:register:0'
|
||||
namespace or a cancellation as defined later in this document.
|
||||
If the client sends a response, it MUST also include the payload
|
||||
corresponding to the challenges 'type' element (which may be empty).
|
||||
</p>
|
||||
<p>
|
||||
After a challenge is received, the client replies to the challenge by
|
||||
sending a <response/> element qualified by the 'urn:xmpp:register:0'
|
||||
namespace or a cancellation as defined later in this document.
|
||||
If the client sends a response, it MUST also include the payload
|
||||
corresponding to the challenges 'type' element (which may be empty).
|
||||
</p>
|
||||
<example caption='Client responds to a challenge'><![CDATA[
|
||||
<response xmlns='urn:xmpp:register:0'>
|
||||
<result xmlns='urn:example:challenge'>Example Response</result>
|
||||
</response>]]></example>
|
||||
<p>
|
||||
After a response is received, if the server needs more information it MAY
|
||||
issue another challenge.
|
||||
For example, if the user has entered their email in response to a
|
||||
challenge, the server might send an email and then issue another challenge
|
||||
asking for the unique code sent in the email.
|
||||
</p>
|
||||
</section2>
|
||||
<section2 topic='Completing Registration or Recovery' anchor='completion'>
|
||||
<p>
|
||||
If after receiving a challenge or response a client or server does not
|
||||
wish to continue registration or recovery, it may send an empty
|
||||
<cancel/> element qualified by the 'urn:xmpp:register:0' namespace.
|
||||
This informs the client or server that registration is complete.
|
||||
This is the same as submitting a data form of type 'cancel' in response to
|
||||
a data form challenge.
|
||||
</p>
|
||||
<example caption='User Cancels Registration or Recovery'><![CDATA[
|
||||
<cancel xmlns='urn:xmpp:register:0'/>]]></example>
|
||||
<p>
|
||||
If the IQ based registration or recovery flow is being used and the server
|
||||
wishes to cancel the flow, it MAY respond to any IQ with the cancel
|
||||
element and type "result".
|
||||
</p>
|
||||
<example caption='Client or server cancels request'><![CDATA[
|
||||
<iq type='result' id='bar'>
|
||||
<cancel xmlns='urn:xmpp:register:0'/>
|
||||
</iq>]]></example>
|
||||
<p>
|
||||
A server may also issue a cancelation IQ with type 'set' if it wishes to
|
||||
cancel after a request/response has been received (ie. when there is no
|
||||
existing IQ to respond to).
|
||||
</p>
|
||||
<example caption='Server cancels flow'><![CDATA[
|
||||
<iq type='set' id='bar'>
|
||||
<cancel xmlns='urn:xmpp:register:0'/>
|
||||
</iq>]]></example>
|
||||
<p>
|
||||
If the client successfully completes all required challenges during stream
|
||||
negotiation the server MUST return a <success/> element qualified by
|
||||
the 'urn:xmpp:register:0' namespace, at which point it may continue with
|
||||
the stream negotiation process.
|
||||
The success element MUST contain a <jid> element containing the bare
|
||||
JID as registered or recovered by the server and a <username>
|
||||
element containing the simple user name for use with SASL (normally this
|
||||
will be the same as the localpart of the JID).
|
||||
</p>
|
||||
<example caption='Server indicates success during steam negotiation'><![CDATA[
|
||||
<success xmlns='urn:xmpp:register:0'>
|
||||
<jid>mercutio@example.net</jid>
|
||||
<username>mercutio</username>
|
||||
</success>]]></example>
|
||||
<p>
|
||||
If the IQ based flow is being used and the server wishes to indicate
|
||||
success after a challenge has been completed it sends an IQ of type "set"
|
||||
containing the <success/> element.
|
||||
</p>
|
||||
<example caption='Server indicates success after stream negotiation'><![CDATA[
|
||||
<iq type='set' id='bar'>
|
||||
<success xmlns='urn:xmpp:register:0'>
|
||||
<jid>mercutio@example.net</jid>
|
||||
<username>mercutio</username>
|
||||
</success>
|
||||
</iq>]]></example>
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Challenges' anchor='challenge'>
|
||||
<p>
|
||||
This document defines several challenges that use existing technologies.
|
||||
</p>
|
||||
<section2 topic='Data Form' anchor='dataform'>
|
||||
<p>
|
||||
This document defines a type of 'jabber:x:data' which MUST always contain a
|
||||
data form (an 'x' element with type 'form') as defined by &xep0004;.
|
||||
Challenges of type 'jabber:x:data' MUST always contain a data form (an 'x'
|
||||
element with type 'form') as defined by &xep0004;.
|
||||
</p>
|
||||
<example caption='Server issues a data form challenge'><![CDATA[
|
||||
<challenge xmlns='urn:xmpp:register:0'
|
||||
@ -446,7 +546,7 @@
|
||||
</section2>
|
||||
<section2 topic='Out of Band Data' anchor='oob'>
|
||||
<p>
|
||||
Challenges of the type "jabber:x:oob" MUST contain an <x/> element
|
||||
Challenges of type "jabber:x:oob" MUST contain an <x/> element
|
||||
qualified by the "jabber:x:oob" namespace as defined in &xep0066;.
|
||||
</p>
|
||||
<example caption='Server issues an OOB challenge'><![CDATA[
|
||||
@ -462,44 +562,54 @@
|
||||
<example caption='Client acknowledges the OOB challenge'><![CDATA[
|
||||
<response xmlns='urn:xmpp:register:0'/>]]></example>
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Completing Registration or Recovery' anchor='completion'>
|
||||
<p>
|
||||
If after receiving a challenge or response a client or server does not wish
|
||||
to continue registration or recovery, it may send an empty <cancel/>
|
||||
element qualified by the 'urn:xmpp:register:0' namespace.
|
||||
This informs the client or server that registration is complete.
|
||||
This is the same as submitting a data form of type 'cancel' in response to a
|
||||
data form challenge.
|
||||
</p>
|
||||
<example caption='User Cancels Registration or Recovery'><![CDATA[
|
||||
<cancel xmlns='urn:xmpp:register:0'/>]]></example>
|
||||
<p>
|
||||
If the IQ based registration or recovery flow is being used and the server
|
||||
wishes to cancel the flow, it MAY respond to any IQ from the client with the
|
||||
cancel element and type "result".
|
||||
</p>
|
||||
<example caption='Server cancels request'><![CDATA[
|
||||
<iq type='result' id='bar'>
|
||||
<cancel xmlns='urn:xmpp:register:0'/>
|
||||
</iq>]]></example>
|
||||
<p>
|
||||
If the client successfully completes all required challenges during stream
|
||||
negotiation the server MUST return an empty <success/> element
|
||||
qualified by the 'urn:xmpp:register:0' namespace, at which point it may
|
||||
continue with the stream negotiation process.
|
||||
If the server needs more information, for example, in the previous challenge
|
||||
the user entered an email and now the server wishes to ask for a code that
|
||||
was sent to that email, the server MAY send another challenge.
|
||||
</p>
|
||||
<example caption='Server indicates success during steam negotiation'><![CDATA[
|
||||
<success xmlns='urn:xmpp:register:0'/>]]></example>
|
||||
<p>
|
||||
If the IQ based flow is being used and the server wishes to indicate success
|
||||
it sends an empty IQ response of type "result".
|
||||
</p>
|
||||
<example caption='Server indicates success after stream negotiation'><![CDATA[
|
||||
<iq type='result' id='bar' />]]></example>
|
||||
<section2 topic='SASL' anchor='sasl'>
|
||||
<p>
|
||||
Servers can support changing passwords by providing a reset flow
|
||||
containing a SASL challenge.
|
||||
The SASL challenge re-uses the SASL profile from &rfc6120;.
|
||||
The server begins by sending the mechanisms list, and the client responds
|
||||
by selecting a mechanism and possibly including initial data.
|
||||
Each step in the SASL process is issued as a new SASL challenge.
|
||||
</p>
|
||||
<example caption='SASL challenge flow'><![CDATA[
|
||||
<!-- Server -->
|
||||
<challenge xmlns='urn:xmpp:register:0'
|
||||
type='urn:ietf:params:xml:ns:xmpp-sasl'>
|
||||
<mechanisms xmlns='urn:ietf:params:xml:ns:xmpp-sasl'>
|
||||
<mechanism>EXTERNAL</mechanism>
|
||||
<mechanism>SCRAM-SHA-1-PLUS</mechanism>
|
||||
<mechanism>SCRAM-SHA-1</mechanism>
|
||||
<mechanism>PLAIN</mechanism>
|
||||
</mechanisms>
|
||||
</challenge>
|
||||
|
||||
<!-- Client -->
|
||||
<response xmlns='urn:xmpp:register:0'>
|
||||
<auth xmlns="urn:ietf:params:xml:ns:xmpp-sasl"
|
||||
mechanism="SCRAM-SHA-1">
|
||||
biwsbj1qdWxpZXQscj1vTXNUQUF3QUFBQU1BQUFBTlAwVEFBQUFBQUJQVTBBQQ==
|
||||
</auth>
|
||||
</response>
|
||||
|
||||
<!-- Server -->
|
||||
<challenge xmlns='urn:xmpp:register:0'
|
||||
type='urn:ietf:params:xml:ns:xmpp-sasl'>
|
||||
<challenge xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
|
||||
cj1vTXNUQUF3QUFBQU1BQUFBTlAwVEFBQUFBQUJQVTBBQWUxMjQ2OTViLTY5Y
|
||||
TktNGRlNi05YzMwLWI1MWIzODA4YzU5ZSxzPU5qaGtZVE0wTURndE5HWTBaaT
|
||||
AwTmpkbUxUa3hNbVV0TkRsbU5UTm1ORE5rTURNeixpPTQwOTY=
|
||||
</challenge>
|
||||
</challenge>
|
||||
|
||||
<!-- Client -->
|
||||
<response xmlns='urn:xmpp:register:0'>
|
||||
<response xmlns="urn:ietf:params:xml:ns:xmpp-sasl">
|
||||
Yz1iaXdzLHI9b01zVEFBd0FBQUFNQUFBQU5QMFRBQUFBQUFCUFUwQUFlMTI0N
|
||||
jk1Yi02OWE5LTRkZTYtOWMzMC1iNTFiMzgwOGM1OWUscD1VQTU3dE0vU3ZwQV
|
||||
RCa0gyRlhzMFdEWHZKWXc9
|
||||
</response>
|
||||
</response>]]></example>
|
||||
</section2>
|
||||
</section1>
|
||||
<section1 topic='Internationalization Considerations' anchor='i18n'>
|
||||
<p>
|
||||
@ -518,10 +628,10 @@
|
||||
Servers that allow in-band registration need to take measures to prevent
|
||||
abuse.
|
||||
Common techniques to prevent spam registrations include displaying CAPTCHAs
|
||||
or requiring proof-of-possession of a valid email address or telephone number
|
||||
by sending a unique code (e.g. an HMAC that can later be verified as having
|
||||
originated at the server) to the users email and requiring that they enter
|
||||
the code before continuing.
|
||||
or requiring proof-of-possession of a valid email address or telephone
|
||||
number by sending a unique code (e.g. an HMAC that can later be verified as
|
||||
having originated at the server) to the users email and requiring that they
|
||||
enter the code before continuing.
|
||||
Servers that do not take such measures risk being black listed by other
|
||||
servers in the network.
|
||||
</p>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user