From dced3d57071da66a869c4788b65c357ad2135102 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 31 Aug 2018 21:03:15 +0100 Subject: [PATCH 1/4] Notes on the format of IS session IDs and tokens --- api/identity/definitions/sid.yaml | 6 +++++- api/identity/email_associations.yaml | 6 ++++++ api/identity/phone_associations.yaml | 6 ++++++ specification/identity_service_api.rst | 25 +++++++++++++++++++------ 4 files changed, 36 insertions(+), 7 deletions(-) diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index 48cc3828..0cf04ed8 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -15,6 +15,10 @@ type: object properties: sid: type: string - description: The session ID. + description: | + The session ID. Session IDs are opaque strings generated by the identity + service. They must consist entirely of the characters + ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they + must not be empty. example: "123abc" required: ['sid'] diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index eb6bc117..b8960dee 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -81,6 +81,12 @@ paths: associate the email address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. + The identity service is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity service. Clients must always pass on the token without + modification. + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index cc5933a8..b0e85adf 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -83,6 +83,12 @@ paths: associate the phone number address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. + The identity service is free to match the token case-insensitively, or + carry out other mapping operations such as unicode + normalisation. Whether to do so is an implementation detail for the + identity service. Clients must always pass on the token without + modification. + Note: for backwards compatibility with previous drafts of this specification, the parameters may also be specified as ``application/x-form-www-urlencoded`` data. However, this usage is diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 33627f70..62853998 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -140,7 +140,7 @@ Some standard error codes are below: third party identifier. :``M_UNKNOWN``: - An unknown error has occurred. + An unknown error has occurred. Privacy ------- @@ -217,11 +217,24 @@ session, within a 24 hour period since its most recent modification. Any attempts to perform these actions after the expiry will be rejected, and a new session should be created and used instead. -To start a session, the client makes a request to the appropriate ``/requestToken`` -endpoint. The user then receives a validation token which should be provided -to the client. The client then provides the token to the appropriate ``/submitToken`` -endpoint, completing the session. At this point, the client should ``/bind`` the -third party identifier or leave it for another entity to bind. +To start a session, the client makes a request to the appropriate +``/requestToken`` endpoint. The identity service then sends a validation token +to the user, and the user provides the token to the client. The client then +provides the token to the appropriate ``/submitToken`` endpoint, completing the +session. At this point, the client should ``/bind`` the third party identifier +or leave it for another entity to bind. + +Format of a validation token +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The format of the validation token is left up to the identity service: it +should choose one appropriate to the 3PID type. (For example, it would be +inappropriate to expect a user to copy a long passphrase including punctuation +from an SMS message into a client.) + +Whatever format the identity service uses, the validation token must consist of +at most 255 Unicode codepoints. Clients must pass the token through without +modification. Email associations ~~~~~~~~~~~~~~~~~~ From 69c30ef15675fa3ece4a55c2ad1233022fcfa9b0 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 31 Aug 2018 21:11:11 +0100 Subject: [PATCH 2/4] spec the format of a client_secret --- api/identity/definitions/request_email_validation.yaml | 6 +++++- api/identity/definitions/request_msisdn_validation.yaml | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/api/identity/definitions/request_email_validation.yaml b/api/identity/definitions/request_email_validation.yaml index 805cd123..c8653456 100644 --- a/api/identity/definitions/request_email_validation.yaml +++ b/api/identity/definitions/request_email_validation.yaml @@ -20,7 +20,11 @@ example: { properties: client_secret: type: string - description: A unique string used to identify the validation attempt. + description: | + A unique string generated by the client, and used to identify the + validation attempt. It must be a string consisting of the characters + ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it + must not be empty. example: "monkeys_are_GREAT" email: type: string diff --git a/api/identity/definitions/request_msisdn_validation.yaml b/api/identity/definitions/request_msisdn_validation.yaml index f8e37d39..ee131660 100644 --- a/api/identity/definitions/request_msisdn_validation.yaml +++ b/api/identity/definitions/request_msisdn_validation.yaml @@ -21,7 +21,11 @@ example: { properties: client_secret: type: string - description: A unique string used to identify the validation attempt. + description: | + A unique string generated by the client, and used to identify the + validation attempt. It must be a string consisting of the characters + ``[0-9a-zA-Z.=_-]``. Its length must not exceed 255 characters and it + must not be empty. example: "monkeys_are_GREAT" country: type: string From cb1e6871964bf3247cc12f325fc2c64f17ed10aa Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 31 Aug 2018 21:16:32 +0100 Subject: [PATCH 3/4] spec the format of an IS invite token --- api/identity/store_invite.yaml | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 89d437a4..69103294 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -84,10 +84,15 @@ paths: properties: token: type: string - description: The generated token. + description: | + The generated token. Must be a string consisting of the + characters ``[0-9a-zA-Z.=_-]``. Its length must not exceed + 255 characters and it must not be empty. public_keys: type: array - description: A list of [server's long-term public key, generated ephemeral public key]. + description: | + A list of [server's long-term public key, generated ephemeral + public key]. items: type: string display_name: From 79974b152c13f570130cbdc96252c692a36dc6a9 Mon Sep 17 00:00:00 2001 From: Richard van der Hoff Date: Fri, 31 Aug 2018 22:44:36 +0100 Subject: [PATCH 4/4] s/identity service/identity server --- api/identity/definitions/sid.yaml | 2 +- api/identity/email_associations.yaml | 4 ++-- api/identity/phone_associations.yaml | 4 ++-- specification/identity_service_api.rst | 6 +++--- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api/identity/definitions/sid.yaml b/api/identity/definitions/sid.yaml index 0cf04ed8..c1f1ae64 100644 --- a/api/identity/definitions/sid.yaml +++ b/api/identity/definitions/sid.yaml @@ -17,7 +17,7 @@ properties: type: string description: | The session ID. Session IDs are opaque strings generated by the identity - service. They must consist entirely of the characters + server. They must consist entirely of the characters ``[0-9a-zA-Z.=_-]``. Their length must not exceed 255 characters and they must not be empty. example: "123abc" diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index b8960dee..df567c48 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -81,10 +81,10 @@ paths: associate the email address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - The identity service is free to match the token case-insensitively, or + The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the - identity service. Clients must always pass on the token without + identity server. Clients must always pass on the token without modification. Note: for backwards compatibility with previous drafts of this diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index b0e85adf..bbd8450e 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -83,10 +83,10 @@ paths: associate the phone number address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - The identity service is free to match the token case-insensitively, or + The identity server is free to match the token case-insensitively, or carry out other mapping operations such as unicode normalisation. Whether to do so is an implementation detail for the - identity service. Clients must always pass on the token without + identity server. Clients must always pass on the token without modification. Note: for backwards compatibility with previous drafts of this diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 62853998..6fc74e14 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -218,7 +218,7 @@ attempts to perform these actions after the expiry will be rejected, and a new session should be created and used instead. To start a session, the client makes a request to the appropriate -``/requestToken`` endpoint. The identity service then sends a validation token +``/requestToken`` endpoint. The identity server then sends a validation token to the user, and the user provides the token to the client. The client then provides the token to the appropriate ``/submitToken`` endpoint, completing the session. At this point, the client should ``/bind`` the third party identifier @@ -227,12 +227,12 @@ or leave it for another entity to bind. Format of a validation token ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The format of the validation token is left up to the identity service: it +The format of the validation token is left up to the identity server: it should choose one appropriate to the 3PID type. (For example, it would be inappropriate to expect a user to copy a long passphrase including punctuation from an SMS message into a client.) -Whatever format the identity service uses, the validation token must consist of +Whatever format the identity server uses, the validation token must consist of at most 255 Unicode codepoints. Clients must pass the token through without modification.