From 6edb90a08e50c75536fa51f7075e42f4703db6e6 Mon Sep 17 00:00:00 2001 From: David Baker Date: Tue, 14 Nov 2017 14:36:38 +0000 Subject: [PATCH] Document threepids Adds the /msisdn' 3pid type and generally fleshes out what a 3pid is and how they work. This merges most of the work from Max Dor in https://github.com/matrix-org/matrix-doc/pull/1039 with some tweaks and additions. --- api/identity/lookup.yaml | 8 +++-- specification/appendices/threepids.rst | 48 ++++++++++++++++++++++++++ specification/identity_service_api.rst | 5 +++ specification/targets.yaml | 1 + 4 files changed, 59 insertions(+), 3 deletions(-) create mode 100644 specification/appendices/threepids.rst diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index 18e5e77d..bd3635b4 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -1,4 +1,6 @@ # Copyright 2016 OpenMarket Ltd +# Copyright 2017 Kamax.io +# Copyright 2017 New Vector Ltd # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -32,13 +34,13 @@ paths: type: string name: medium required: true - description: The literal string "email". + description: The medium type of the 3pid. See `Appendices`_. x-example: "email" - in: query type: string name: address required: true - description: The email address being looked up. + description: The address of the 3pid being looked up. See `Appendices`_. x-example: "louise@bobs.burgers" responses: 200: @@ -82,4 +84,4 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity service which show that the association should be trusted, if you trust the verifying identity service. + description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. diff --git a/specification/appendices/threepids.rst b/specification/appendices/threepids.rst new file mode 100644 index 00000000..2f8147a8 --- /dev/null +++ b/specification/appendices/threepids.rst @@ -0,0 +1,48 @@ +.. Copyright 2017 Kamax.io +.. +.. Licensed under the Apache License, Version 2.0 (the "License"); +.. you may not use this file except in compliance with the License. +.. You may obtain a copy of the License at +.. +.. http://www.apache.org/licenses/LICENSE-2.0 +.. +.. Unless required by applicable law or agreed to in writing, software +.. distributed under the License is distributed on an "AS IS" BASIS, +.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +.. See the License for the specific language governing permissions and +.. limitations under the License. + +3PID Types +---------- +3PIDs represent identifiers on other namespaces that might be associated with a +particular person. They comprise a tuple of `medium` which is a string that +identifies the namespace in which the identifier exists and an `address`: a +string representing the identifier in that namespace. This must be a canonical +form of the identifier, ie. if multiple strings could represent the same +identifier, only one of these strings must be used in a 3PID address, in a +well-defined manner. + +For example, for e-mail, the `medium` is 'email' and the `address` would be the +email address, eg. the string 'bob@example.com'. Since domain resolution is +case-insensitive, the email address 'bob@Example.com' also has a 3PID address +of 'bob@example.com' and not 'bob@Example.com'. + +The namespaces defined by this specification are listed below. More namespaces +may be defined in future versions of this specification. + +E-Mail +~~~~~~ +Medium: `email` + +Represents E-Mail addresses. The `address` is the raw email address in +user@domain form with the domain in lowercase. It must not contain other text +such as real name, angle brackets or a mailto: prefix. + +PSTN Phone numbers +~~~~~~~~~~~~~~~~~~ +Medium: `msisdn` + +Represents telephone numbers on the public switched telephone network. The +`address` is the telephone number represented as a MSISDN (Mobile Station +International Subscriber Directory Number) as defined by the E.164 numbering +plan. Note that MSISDNs do not include a leading '+'. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index fa03e162..90b20d23 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -1,4 +1,6 @@ .. Copyright 2016 OpenMarket Ltd +.. Copyright 2017 Kamax.io +.. Copyright 2017 New Vector Ltd .. .. Licensed under the Apache License, Version 2.0 (the "License"); .. you may not use this file except in compliance with the License. @@ -52,6 +54,8 @@ necessarily provide evidence that they have validated associations, but claim to have done so. Establishing the trustworthiness of an individual identity service is left as an exercise for the client. +3PID types are described in the `Appendices`_. + Privacy ------- @@ -291,3 +295,4 @@ It will look up ``token`` which was stored in a call to ``store-invite``, and fe } .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 +.. _`Appendices`: ../appendices.html#threepids diff --git a/specification/targets.yaml b/specification/targets.yaml index fb68e13d..6a52fd84 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -33,6 +33,7 @@ targets: files: - appendices.rst - appendices/base64.rst + - appendices/threepids.rst - appendices/signing_json.rst - appendices/identifier_grammar.rst - appendices/threat_model.rst