From 19c32fce88eefccbe461e789be55c08afb8b94cb Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Wed, 6 May 2020 09:02:30 -0400 Subject: [PATCH 1/5] XEP-0389: inline examples in Retrieving the Flows --- xep-0389.xml | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/xep-0389.xml b/xep-0389.xml index 502eb949..2f0980fe 100644 --- a/xep-0389.xml +++ b/xep-0389.xml @@ -293,19 +293,17 @@ <register> or <recovery> element qualified by the "urn:xmpp:register:0" namespace.

+ + +]]>

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 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. - If an entity supports this specification but does not provide any flows - after stream negotiation it MUST respond with an empty list.

- - -]]> @@ -324,6 +322,10 @@ ]]> +

+ If an entity supports this specification but does not provide any flows + after stream negotiation it MUST respond with an empty list. +

From 05eaea263d721f1984f8c7ecaea990c0827e5dc8 Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Wed, 6 May 2020 09:17:36 -0400 Subject: [PATCH 2/5] XEP-0389: always require disco/caps feature --- xep-0389.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/xep-0389.xml b/xep-0389.xml index 2f0980fe..bcfb31e8 100644 --- a/xep-0389.xml +++ b/xep-0389.xml @@ -275,9 +275,9 @@

Clients, servers, and other services such as components that support - Extensible IBR after stream negotiation is complete MUST advertise the - fact by including a feature of "urn::xmpp:register:0" in response to - &xep0030; information requests and in their &xep0115; profiles. + Extensible IBR MUST advertise the fact by including a feature of + "urn::xmpp:register:0" in response to &xep0030; information requests and + in their &xep0115; profiles.

From 9a7d41bcd8e7f8d912b845e2fef40c4ee8129e68 Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Wed, 6 May 2020 09:20:28 -0400 Subject: [PATCH 3/5] XEP-0389: move Disco section to the top --- xep-0389.xml | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/xep-0389.xml b/xep-0389.xml index bcfb31e8..a22a6a1b 100644 --- a/xep-0389.xml +++ b/xep-0389.xml @@ -196,6 +196,20 @@ +

+ Clients, servers, and other services such as components that support + Extensible IBR MUST advertise the fact by including a feature of + "urn::xmpp:register:0" in response to &xep0030; information requests and in + their &xep0115; profiles. +

+ + … + + … +]]> + +

If a server supports registering for or recovering an account using @@ -271,20 +285,6 @@ ]]> - - -

- Clients, servers, and other services such as components that support - Extensible IBR MUST advertise the fact by including a feature of - "urn::xmpp:register:0" in response to &xep0030; information requests and - in their &xep0115; profiles. -

- - … - - … -]]>

From a8b67624ac66c27c39991c2eec19f4a57953b32b Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Wed, 6 May 2020 09:23:06 -0400 Subject: [PATCH 4/5] XEP-0389: add intro to flows section --- xep-0389.xml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/xep-0389.xml b/xep-0389.xml index a22a6a1b..204760c0 100644 --- a/xep-0389.xml +++ b/xep-0389.xml @@ -210,6 +210,16 @@ ]]> +

+ Registration or recovery is completed after responding to a series of + challenges issued by the server. + Challenges are grouped in to "flows", a number of challenges that may be + issued together to complete an action. + For example, a registration flow might be created that issues a data form + challenge which will be shown to the user to gather information, then issues + a second data form challenge to let the user enter a confirmation code that + was sent to their email. +

If a server supports registering for or recovering an account using From ae5f2c7ade19855353da3307a63a334d9570516b Mon Sep 17 00:00:00 2001 From: Sam Whited Date: Wed, 20 May 2020 09:48:21 -0400 Subject: [PATCH 5/5] XEP-0389: overhaul document structure This also adds more information to the element to make flows where the server assigns the JID possible. --- xep-0389.xml | 284 +++++++++++++++++++++++++++++++++++---------------- 1 file changed, 197 insertions(+), 87 deletions(-) diff --git a/xep-0389.xml b/xep-0389.xml index 204760c0..a95c8ffa 100644 --- a/xep-0389.xml +++ b/xep-0389.xml @@ -31,6 +31,19 @@ ibr2 &sam; + + 0.5.0 + 2020-05-26 + ssw + +

    +
  • Overhaul document for readability.
    • +
  • Add JID and username information to success element.
    • +
  • Always require disco/caps feature.
    • +
  • More examples.
    • +
+ + 0.4.0 2020-04-22 @@ -209,7 +222,7 @@ … ]]> - +

Registration or recovery is completed after responding to a series of challenges issued by the server. @@ -223,15 +236,16 @@

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 @@ ]]> +

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

+

+ Registration or recovery may also be completed after stream neogtiation if + server policy allows it. +

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

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

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

]]> - - -

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

+ +

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

]]> -

- 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". +

+ 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".

- ]]> -

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

+

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

Payload ]]> -

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

+

+ 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). +

Example Response ]]> +

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

+ + +

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

+ ]]> +

+ 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". +

+ + +]]> +

+ 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). +

+ + +]]> +

+ 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). +

+ + mercutio@example.net + mercutio +]]> +

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

+ + + mercutio@example.net + mercutio + +]]> + + + +

+ This document defines several challenges that use existing technologies. +

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

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

]]> - - -

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

- ]]> -

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

- - -]]> -

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

- ]]> -

- If the IQ based flow is being used and the server wishes to indicate success - it sends an empty IQ response of type "result". -

- ]]> + +

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

+ + + + EXTERNAL + SCRAM-SHA-1-PLUS + SCRAM-SHA-1 + PLAIN + + + + + + + biwsbj1qdWxpZXQscj1vTXNUQUF3QUFBQU1BQUFBTlAwVEFBQUFBQUJQVTBBQQ== + + + + + + + cj1vTXNUQUF3QUFBQU1BQUFBTlAwVEFBQUFBQUJQVTBBQWUxMjQ2OTViLTY5Y + TktNGRlNi05YzMwLWI1MWIzODA4YzU5ZSxzPU5qaGtZVE0wTURndE5HWTBaaT + AwTmpkbUxUa3hNbVV0TkRsbU5UTm1ORE5rTURNeixpPTQwOTY= + + + + + + + Yz1iaXdzLHI9b01zVEFBd0FBQUFNQUFBQU5QMFRBQUFBQUFCUFUwQUFlMTI0N + jk1Yi02OWE5LTRkZTYtOWMzMC1iNTFiMzgwOGM1OWUscD1VQTU3dE0vU3ZwQV + RCa0gyRlhzMFdEWHZKWXc9 + +]]> +

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