wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge branch 'm-master' into travis/general/3pid_invite

Browse source
This commit is contained in:
Travis Ralston 2018-08-30 15:01:31 -06:00
commit d57b977a55
189 changed files with 4567 additions and 1219 deletions
Download patch file Download diff file Expand all files Collapse all files

170
specification/identity_service_api.rst
View file

@ -1,6 +1,7 @@
.. Copyright 2016 OpenMarket Ltd
.. Copyright 2017 Kamax.io
.. Copyright 2017 New Vector Ltd
.. Copyright 2018 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.
@ -23,18 +24,32 @@ user identifiers. From time to time, it is useful to refer to users by other
number. This identity service specification describes how mappings between
third-party identifiers and Matrix user identifiers can be established,
validated, and used. This description technically may apply to any 3pid, but in
practice has only been applied specifically to email addresses.
practice has only been applied specifically to email addresses and phone numbers.
.. contents:: Table of Contents
.. sectnum::
Specification version
---------------------
Changelog
---------
.. topic:: Version: %IDENTITY_RELEASE_LABEL%
{{identity_service_changelog}}
This version of the specification is generated from
`matrix-doc <https://github.com/matrix-org/matrix-doc>`_ as of Git commit
`{{git_version}} <https://github.com/matrix-org/matrix-doc/tree/{{git_rev}}>`_.
For the full historical changelog, see
https://github.com/matrix-org/matrix-doc/blob/master/changelogs/identity_service.rst
Other versions of this specification
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following other versions are also available, in reverse chronological order:
- `HEAD <https://matrix.org/docs/spec/identity_service/unstable.html>`_: Includes all changes since the latest versioned release.
General principles
------------------
@ -56,6 +71,75 @@ is left as an exercise for the client.
3PID types are described in `3PID Types`_ Appendix.
API standards
-------------
The mandatory baseline for identity service communication in Matrix is exchanging
JSON objects over HTTP APIs. HTTPS is required for communication, and all API calls
use a Content-Type of ``application/json``. In addition, strings MUST be encoded as
UTF-8.
Any errors which occur at the Matrix API level MUST return a "standard error response".
This is a JSON object which looks like:
.. code:: json
{
"errcode": "<error code>",
"error": "<error message>"
}
The ``error`` string will be a human-readable error message, usually a sentence
explaining what went wrong. The ``errcode`` string will be a unique string
which can be used to handle an error message e.g. ``M_FORBIDDEN``. There may be
additional keys depending on the error, but the keys ``error`` and ``errcode``
MUST always be present.
Some standard error codes are below:
:``M_NOT_FOUND``:
The resource requested could not be located.
:``M_MISSING_PARAMS``:
The request was missing one or more parameters.
:``M_INVALID_PARAM``:
The request contained one or more invalid parameters.
:``M_SESSION_NOT_VALIDATED``:
The session has not been validated.
:``M_NO_VALID_SESSION``:
A session could not be located for the given parameters.
:``M_SESSION_EXPIRED``:
The session has expired and must be renewed.
:``M_INVALID_EMAIL``:
The email address provided was not valid.
:``M_EMAIL_SEND_ERROR``:
There was an error sending an email. Typically seen when attempting to verify
ownership of a given email address.
:``M_INVALID_ADDRESS``:
The provided third party address was not valid.
:``M_SEND_ERROR``:
There was an error sending a notification. Typically seen when attempting to
verify ownership of a given third party address.
:``M_UNRECOGNIZED``:
The request contained an unrecognised value, such as an unknown token or medium.
:``M_THREEPID_IN_USE``:
The third party identifier is already in use by another user. Typically this
error will have an additional ``mxid`` property to indicate who owns the
third party identifier.
:``M_UNKNOWN``:
An unknown error has occurred.
Privacy
-------
@ -67,6 +151,22 @@ should allow a 3pid to be mapped to a Matrix user identity, but not in the other
direction (i.e. one should not be able to get all 3pids associated with a Matrix
user ID, or get all 3pids associated with a 3pid).
Web browser clients
-------------------
It is realistic to expect that some clients will be written to be run within a web
browser or similar environment. In these cases, the identity service should respond to
pre-flight requests and supply Cross-Origin Resource Sharing (CORS) headers on all
requests.
When a client approaches the server with a pre-flight (OPTIONS) request, the server
should respond with the CORS headers for that route. The recommended CORS headers
to be returned by servers on all requests are::
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept, Authorization
Status check
------------
@ -77,8 +177,7 @@ Key management
An identity service has some long-term public-private keypairs. These are named
in a scheme ``algorithm:identifier``, e.g. ``ed25519:0``. When signing an
association, the Matrix standard JSON signing format is used, as specified in
the server-server API specification under the heading "Signing Events".
association, the standard `Signing JSON`_ algorithm applies.
.. TODO: Actually allow identity services to revoke all keys
See: https://github.com/matrix-org/matrix-doc/issues/1633
@ -86,18 +185,18 @@ the server-server API specification under the heading "Signing Events".
An HTTP API is offered to get public keys, and check whether a particular key is
valid.
The identity server may also keep track of some short-term public-private
The identity service may also keep track of some short-term public-private
keypairs, which may have different usage and lifetime characteristics than the
service's long-term keys.
{{pubkey_is_http_api}}
Association Lookup
Association lookup
------------------
{{lookup_is_http_api}}
Establishing Associations
Establishing associations
-------------------------
The flow for creating an association is session-based.
@ -116,63 +215,52 @@ 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.
Email associations
~~~~~~~~~~~~~~~~~~
{{email_associations_is_http_api}}
Phone number associations
~~~~~~~~~~~~~~~~~~~~~~~~~
{{phone_associations_is_http_api}}
General
~~~~~~~
{{associations_is_http_api}}
Invitation Storage
Invitation storage
------------------
An identity service can store pending invitations to a user's 3pid, which will
be retrieved and can be either notified on or look up when the 3pid is
associated with a Matrix user ID.
At a later point, if the owner of that particular 3pid binds it with a Matrix user ID, the identity server will attempt to make an HTTP POST to the Matrix user's homeserver which looks roughly as below::
POST https://bar.com:8448/_matrix/federation/v1/3pid/onbind
Content-Type: application/json
{
"medium": "email",
"address": "foo@bar.baz",
"mxid": "@alice:example.tld",
"invites": [
{
"medium": "email",
"address": "foo@bar.baz",
"mxid": "@alice:example.tld",
"room_id": "!something:example.tld",
"sender": "@bob:example.tld",
"signed": {
"mxid": "@alice:example.tld",
"signatures": {
"vector.im": {
"ed25519:0": "somesignature"
}
},
"token": "sometoken"
}
}
]
}
Where the signature is produced using a long-term private key.
At a later point, if the owner of that particular 3pid binds it with a Matrix user
ID, the identity service will attempt to make an HTTP POST to the Matrix user's
homeserver via the `/3pid/onbind`_ endpoint. The request MUST be signed with a
long-term private key for the identity service.
{{store_invite_is_http_api}}
Ephemeral invitation signing
----------------------------
To aid clients who may not be able to perform crypto themselves, the identity service offers some crypto functionality to help in accepting invitations.
This is less secure than the client doing it itself, but may be useful where this isn't possible.
To aid clients who may not be able to perform crypto themselves, the identity
service offers some crypto functionality to help in accepting invitations.
This is less secure than the client doing it itself, but may be useful where
this isn't possible.
{{invitation_signing_is_http_api}}
.. _`Unpadded Base64`: ../appendices.html#unpadded-base64
.. _`3PID Types`: ../appendices.html#pid-types
.. _`Signing JSON`: ../appendices.html#signing-json
.. _`/3pid/onbind`: ../server_server/unstable.html#put-matrix-federation-v1-3pid-onbind