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.
pull/977/head
David Baker 7 years ago
parent 202a265d85
commit 6edb90a08e

@ -1,4 +1,6 @@
# Copyright 2016 OpenMarket Ltd # Copyright 2016 OpenMarket Ltd
# Copyright 2017 Kamax.io
# Copyright 2017 New Vector Ltd
# #
# Licensed under the Apache License, Version 2.0 (the "License"); # Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License. # you may not use this file except in compliance with the License.
@ -32,13 +34,13 @@ paths:
type: string type: string
name: medium name: medium
required: true required: true
description: The literal string "email". description: The medium type of the 3pid. See `Appendices`_.
x-example: "email" x-example: "email"
- in: query - in: query
type: string type: string
name: address name: address
required: true 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" x-example: "louise@bobs.burgers"
responses: responses:
200: 200:
@ -82,4 +84,4 @@ paths:
description: The unix timestamp at which the association was verified. description: The unix timestamp at which the association was verified.
signatures: signatures:
type: object 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.

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

@ -1,4 +1,6 @@
.. Copyright 2016 OpenMarket Ltd .. Copyright 2016 OpenMarket Ltd
.. Copyright 2017 Kamax.io
.. Copyright 2017 New Vector Ltd
.. ..
.. Licensed under the Apache License, Version 2.0 (the "License"); .. Licensed under the Apache License, Version 2.0 (the "License");
.. you may not use this file except in compliance with 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 have done so. Establishing the trustworthiness of an individual identity service
is left as an exercise for the client. is left as an exercise for the client.
3PID types are described in the `Appendices`_.
Privacy 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 .. _`Unpadded Base64`: ../appendices.html#unpadded-base64
.. _`Appendices`: ../appendices.html#threepids

@ -33,6 +33,7 @@ targets:
files: files:
- appendices.rst - appendices.rst
- appendices/base64.rst - appendices/base64.rst
- appendices/threepids.rst
- appendices/signing_json.rst - appendices/signing_json.rst
- appendices/identifier_grammar.rst - appendices/identifier_grammar.rst
- appendices/threat_model.rst - appendices/threat_model.rst

Loading…
Cancel
Save