From b0194a3016e84f27ab25873221e6059e002d8847 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 14:50:17 +0100 Subject: [PATCH 1/8] Spec for endpoint-specific 3pid verification token As per proposal https://docs.google.com/document/d/13mapDbaOnbob9ZYRDiGm1YbeZhFOBj_R1OvgBA9pA5s/edit?pref=2&pli=1# --- api/client-server/registration.yaml | 52 +++++++++++++++++++++++++- specification/identity_service_api.rst | 5 +++ 2 files changed, 56 insertions(+), 1 deletion(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index e5875225..a67ce2a1 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -132,9 +132,59 @@ paths: "$ref": "definitions/error.yaml" tags: - User data + "/register/email/requestToken": + post: + summary: Requests a validation token be sent to the given email address + description: |- + Proxies the identity server API `validate/email/requestToken`, but + additionally inform the user if the given email is already associated + with an account on this Home Server. Note that, for consistency, + this API takes JSON objects, though the Identity Server API takes + ``x-www-form-urlencoded`` parameters. See the Identity Server API for + further information, including the full list of response coes. + parameters: + - in: body + name: body + schema: + type: object + properties: + client_secret: + type: string + description: Client-generated secret string used to protect this session + example: "this_is_my_secret_string" + email: + type: string + description: The email address + example: "example@example.com" + send_attempt: + type: number + description: Used to distinguish protocol level retries from requests to re-send the email. + example: "1" + required: ["client_secret", "email", "send_attempt"] + responses: + 200: + description: |- + An email has been sent to the specified address. + Note that this may be an email containing the validation token or it may be informing + the user of an error. + examples: + application/json: "{}" + schema: + type: object + 400: + description: |- + Returns an error object indicating the nature of the error. A Home Server may use + ``M_THREEPID_IN_USE`` to inform the user that the email address is already registered + to an account on this server, however, if the home server has the ability to send email, + it is recommended that the server instead send an email to the user with instructions + on how to reset their password. + examples: + application/json: '{"errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use"}' + schema: + type: object "/account/password": post: - summary: Changes a user's password. + summary: "Changes a user's password." description: |- Changes the password for an account on this homeserver. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 0aa34343..d6f5d324 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -124,6 +124,11 @@ This is to avoid repeatedly sending the same email in the case of request retries between the POSTing user and the identity service. The client should increment this value if they desire a new email (e.g. a reminder) to be sent. +Note that Home Servers offer APIs that proxy this API, adding additional +behaviour on top, for example, ``/register/email/requestToken`` is designed +specifically for use when registering an account and therefore will inform +the user if the email address given is already registered on the server. + Validating ownership of an email ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 6a0c9edb49bd9f011f8fd6a9ac049056310c9050 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 15:19:44 +0100 Subject: [PATCH 2/8] Add the id_server param --- api/client-server/registration.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index a67ce2a1..0334ec94 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -148,6 +148,10 @@ paths: schema: type: object properties: + id_server: + type: string + description: The ID server to send the onward request to as a hostname with an appended colon and port number if the port is not the default. + example: "id.matrix.org" client_secret: type: string description: Client-generated secret string used to protect this session From 60293af83a721f61d600699e0b1a3e8641e30f06 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 15:25:09 +0100 Subject: [PATCH 3/8] PR feedback --- api/client-server/registration.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 0334ec94..5301bfef 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -136,8 +136,8 @@ paths: post: summary: Requests a validation token be sent to the given email address description: |- - Proxies the identity server API `validate/email/requestToken`, but - additionally inform the user if the given email is already associated + Proxies the identity server API ``validate/email/requestToken``, but + first checks that the given email address is not already associated with an account on this Home Server. Note that, for consistency, this API takes JSON objects, though the Identity Server API takes ``x-www-form-urlencoded`` parameters. See the Identity Server API for From 572aa24a88ef8d03ac536b9a43b33d2adb33b399 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 15:40:20 +0100 Subject: [PATCH 4/8] Add M_THREEPID_IN_USE --- specification/client_server_api.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index dd93f774..eba551d2 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -113,6 +113,9 @@ Some requests have unique error codes: :``M_BAD_PAGINATION``: Encountered when specifying bad pagination query parameters. +:``M_THREEPID_IN_USE``: + Sent when a threepid given to an API cannot be used because the same threepid is already in use. + .. _sect:txn_ids: The client-server API typically uses ``HTTP PUT`` to submit requests with a From a600386c050a00c099295b72953e5bc857be18af Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 16:12:11 +0100 Subject: [PATCH 5/8] Consistent working for error response Also format json example better --- api/client-server/registration.yaml | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 5301bfef..f6803b88 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -177,13 +177,16 @@ paths: type: object 400: description: |- - Returns an error object indicating the nature of the error. A Home Server may use - ``M_THREEPID_IN_USE`` to inform the user that the email address is already registered - to an account on this server, however, if the home server has the ability to send email, - it is recommended that the server instead send an email to the user with instructions - on how to reset their password. + The request was invalid. An errcode of ``M_THREEPID_IN_USE`` is used to inform the user + that the email address is already registered to an account on this server, however, + if the home server has the ability to send email, it is recommended that the server + instead send an email to the user with instructions on how to reset their password. examples: - application/json: '{"errcode": "M_THREEPID_IN_USE", "error": "The specified address is already in use"}' + application/json: |- + { + "errcode": "M_THREEPID_IN_USE", + "error": "The specified address is already in use" + } schema: type: object "/account/password": From 3dddc0dcdf751e326a1e36e32d75e2d3db4b84f4 Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 16:13:45 +0100 Subject: [PATCH 6/8] Explain why not erroring on dup 3pid is desireable --- api/client-server/registration.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index f6803b88..6d99aca2 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -181,6 +181,8 @@ paths: that the email address is already registered to an account on this server, however, if the home server has the ability to send email, it is recommended that the server instead send an email to the user with instructions on how to reset their password. + This prevents malicious parties from being able to determine if a given email address + has an account on the Home Server in question. examples: application/json: |- { From e4db7be8e27a48c77ee23f60462791769b27a14f Mon Sep 17 00:00:00 2001 From: David Baker Date: Thu, 30 Jun 2016 16:22:01 +0100 Subject: [PATCH 7/8] Better structure for error response & add server not trusted error --- api/client-server/registration.yaml | 15 +++++++++------ specification/client_server_api.rst | 3 +++ 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index 6d99aca2..ce50e13a 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -177,12 +177,15 @@ paths: type: object 400: description: |- - The request was invalid. An errcode of ``M_THREEPID_IN_USE`` is used to inform the user - that the email address is already registered to an account on this server, however, - if the home server has the ability to send email, it is recommended that the server - instead send an email to the user with instructions on how to reset their password. - This prevents malicious parties from being able to determine if a given email address - has an account on the Home Server in question. + Part of the request was invalid. This may include one of the following error codes: + + * ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server. + however, if the home server has the ability to send email, it is recommended that the server + instead send an email to the user with instructions on how to reset their password. + This prevents malicious parties from being able to determine if a given email address + has an account on the Home Server in question. + * ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server + that is not trusted by this Home Server. examples: application/json: |- { diff --git a/specification/client_server_api.rst b/specification/client_server_api.rst index eba551d2..1e9feaff 100644 --- a/specification/client_server_api.rst +++ b/specification/client_server_api.rst @@ -116,6 +116,9 @@ Some requests have unique error codes: :``M_THREEPID_IN_USE``: Sent when a threepid given to an API cannot be used because the same threepid is already in use. +:``M_SERVER_NOT_TRUSTED``: + The client's request used a third party server, eg. ID server, that this server does not trust. + .. _sect:txn_ids: The client-server API typically uses ``HTTP PUT`` to submit requests with a From 14ff3862e3c7c5b602523bc22db346fde72474ec Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 5 Jul 2016 15:15:44 +0100 Subject: [PATCH 8/8] More PR feedback --- api/client-server/registration.yaml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/api/client-server/registration.yaml b/api/client-server/registration.yaml index ce50e13a..f2e50390 100644 --- a/api/client-server/registration.yaml +++ b/api/client-server/registration.yaml @@ -141,7 +141,7 @@ paths: with an account on this Home Server. Note that, for consistency, this API takes JSON objects, though the Identity Server API takes ``x-www-form-urlencoded`` parameters. See the Identity Server API for - further information, including the full list of response coes. + further information. parameters: - in: body name: body @@ -180,7 +180,7 @@ paths: Part of the request was invalid. This may include one of the following error codes: * ``M_THREEPID_IN_USE`` : The email address is already registered to an account on this server. - however, if the home server has the ability to send email, it is recommended that the server + However, if the home server has the ability to send email, it is recommended that the server instead send an email to the user with instructions on how to reset their password. This prevents malicious parties from being able to determine if a given email address has an account on the Home Server in question.