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

Fix all naming cases of "identity service"

Browse source 
Fixes https://github.com/matrix-org/matrix-doc/issues/1396

Includes some "homeserver" fixes too. This commit does not include historical documentation or notes.
This commit is contained in:
Travis Ralston 2018-08-30 18:19:35 -06:00
parent 683072e624
commit cc0badaaa1
14 changed files with 90 additions and 90 deletions
Download patch file Download diff file Expand all files Collapse all files

14
api/client-server/administrative_contact.yaml
View file

@ -35,7 +35,7 @@ paths:
associated with the user's account.
This is *not* the same as the list of third party identifiers bound to
the user's Matrix ID in Identity Servers.
the user's Matrix ID in Identity Services.
Identifiers in this list may be used by the homeserver as, for example,
identifiers that it will accept to reset the user's account password.
@ -106,13 +106,13 @@ paths:
properties:
client_secret:
type: string
description: The client secret used in the session with the Identity Server.
description: The client secret used in the session with the Identity Service.
id_server:
type: string
description: The Identity Server to use.
description: The Identity Service to use.
sid:
type: string
description: The session identifier given by the Identity Server.
description: The session identifier given by the Identity Service.
required: ["client_secret", "id_server", "sid"]
bind:
type: boolean
@ -138,11 +138,11 @@ paths:
schema:
type: object
403:
description: The credentials could not be verified with the identity server.
description: The credentials could not be verified with the identity service.
examples:
application/json: {
"errcode": "M_THREEPID_AUTH_FAILED",
"error": "The third party credentials could not be verified by the identity server."
"error": "The third party credentials could not be verified by the identity service."
}
schema:
"$ref": "definitions/errors/error.yaml"
@ -243,7 +243,7 @@ paths:
description: |-
Proxies the identity service API ``validate/msisdn/requestToken``, but
first checks that the given phone number is **not** already associated
with an account on this Home Server. This API should be used to request
with an account on this homeserver. This API should be used to request
validation tokens when adding a phone number to an account. This API's
parameters and response are identical to that of the |/register/msisdn/requestToken|_
endpoint.

12
api/client-server/create_room.yaml
View file

@ -41,7 +41,7 @@ paths:
0. A default ``m.room.power_levels`` event, giving the room creator
(and not other members) permission to send state events. Overridden
by the ``power_level_content_override`` parameter.
1. Events set by the ``preset``. Currently these are the ``m.room.join_rules``,
``m.room.history_visibility``, and ``m.room.guest_access`` state events.
@ -59,13 +59,13 @@ paths:
======================== ============== ====================== ================ =========
Preset ``join_rules`` ``history_visibility`` ``guest_access`` Other
======================== ============== ====================== ================ =========
``private_chat`` ``invite`` ``shared`` ``can_join``
``private_chat`` ``invite`` ``shared`` ``can_join``
``trusted_private_chat`` ``invite`` ``shared`` ``can_join`` All invitees are given the same power level as the room creator.
``public_chat`` ``public`` ``shared`` ``forbidden``
``public_chat`` ``public`` ``shared`` ``forbidden``
======================== ============== ====================== ================ =========
The server will create a ``m.room.create`` event in the room with the
requesting user as the creator, alongside other keys provided in the
requesting user as the creator, alongside other keys provided in the
``creation_content``.
operationId: createRoom
security:
@ -138,7 +138,7 @@ paths:
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
description: The hostname+port of the identity service which should be used for third party identifier lookups.
medium:
type: string
# TODO: Link to identity service spec when it eixsts
@ -196,7 +196,7 @@ paths:
If unspecified, the server should use the ``visibility`` to determine
which preset to use. A visbility of ``public`` equates to a preset of
``public_chat`` and ``private`` visibility equates to a preset of
``public_chat`` and ``private`` visibility equates to a preset of
``private_chat``.
is_direct:
type: boolean

6
api/client-server/definitions/wellknown/identity_server.yaml
View file

@ -11,14 +11,14 @@
# 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.
title: Identity Server Information
title: Identity Service Information
description: |-
Used by clients to discover identity server information.
Used by clients to discover identity service information.
type: object
properties:
base_url:
type: string
description: The base URL for the identity server for client-server connections.
description: The base URL for the identity service for client-server connections.
example: https://identity.example.com
required:
- base_url

16
api/client-server/registration.yaml
View file

@ -92,7 +92,7 @@ paths:
type: boolean
description: |-
If true, the server binds the email used for authentication to
the Matrix ID with the ID Server.
the Matrix ID with the identity service.
example: false
username:
type: string
@ -251,7 +251,7 @@ paths:
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 homeserver in question.
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an ID server
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity service
that is not trusted by this homeserver.
examples:
application/json: {
@ -307,12 +307,12 @@ paths:
Part of the request was invalid. This may include one of the following error codes:
* ``M_THREEPID_IN_USE`` : The phone number is already registered to an account on this server.
However, if the home server has the ability to send SMS message, it is recommended that the server
However, if the homeserver has the ability to send SMS message, it is recommended that the server
instead send an SMS message to the user with instructions on how to reset their password.
This prevents malicious parties from being able to determine if a given phone number
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.
has an account on the homeserver in question.
* ``M_SERVER_NOT_TRUSTED`` : The ``id_server`` parameter refers to an identity service
that is not trusted by this homeserver.
examples:
application/json: {
"errcode": "M_THREEPID_IN_USE",
@ -375,7 +375,7 @@ paths:
description: |-
Proxies the identity service API ``validate/email/requestToken``, but
first checks that the given email address **is** associated with an account
on this Home Server. This API should be used to request
on this homeserver. This API should be used to request
validation tokens when authenticating for the
`account/password` endpoint. This API's parameters and response are
identical to that of the HS API |/register/email/requestToken|_ except that
@ -437,7 +437,7 @@ paths:
description: |-
Proxies the identity service API ``validate/msisdn/requestToken``, but
first checks that the given phone number **is** associated with an account
on this Home Server. This API should be used to request
on this homeserver. This API should be used to request
validation tokens when authenticating for the
`account/password` endpoint. This API's parameters and response are
identical to that of the HS API |/register/msisdn/requestToken|_ except that

16
api/client-server/third_party_membership.yaml
View file

@ -36,7 +36,7 @@ paths:
*Note that there are two forms of this API, which are documented separately.
This version of the API does not require that the inviter know the Matrix
identifier of the invitee, and instead relies on third party identifiers.
The homeserver uses an identity server to perform the mapping from
The homeserver uses an identity service to perform the mapping from
third party identifier to a Matrix identifier. The other is documented in the*
`joining rooms section`_.
@ -47,31 +47,31 @@ paths:
Only users currently in a particular room can invite other users to
join that room.
If the identity server did know the Matrix user identifier for the
If the identity service did know the Matrix user identifier for the
third party identifier, the homeserver will append a ``m.room.member``
event to the room.
If the identity server does not know a Matrix user identifier for the
If the identity service does not know a Matrix user identifier for the
passed third party identifier, the homeserver will issue an invitation
which can be accepted upon providing proof of ownership of the third
party identifier. This is achieved by the identity server generating a
party identifier. This is achieved by the identity service generating a
token, which it gives to the inviting homeserver. The homeserver will
add an ``m.room.third_party_invite`` event into the graph for the room,
containing that token.
When the invitee binds the invited third party identifier to a Matrix
user ID, the identity server will give the user a list of pending
user ID, the identity service will give the user a list of pending
invitations, each containing:
- The room ID to which they were invited
- The token given to the homeserver
- A signature of the token, signed with the identity server's private key
- A signature of the token, signed with the identity service's private key
- The matrix user ID who invited them to the room
If a token is requested from the identity server, the homeserver will
If a token is requested from the identity service, the homeserver will
append a ``m.room.third_party_invite`` event to the room.
.. _joining rooms section: `invite-by-user-id-endpoint`_
@ -98,7 +98,7 @@ paths:
properties:
id_server:
type: string
description: The hostname+port of the identity server which should be used for third party identifier lookups.
description: The hostname+port of the identity service which should be used for third party identifier lookups.
medium:
type: string
# TODO: Link to identity service spec when it eixsts

2
api/client-server/wellknown.yaml
View file

@ -54,7 +54,7 @@ paths:
description: Information about the homeserver to connect to.
"$ref": "definitions/wellknown/homeserver.yaml"
m.identity_server:
description: Optional. Information about the identity server to connect to.
description: Optional. Information about the identity service to connect to.
"$ref": "definitions/wellknown/identity_server.yaml"
additionalProperties:
description: Application-dependent keys using Java package naming convention.

18
api/server-server/third_party_invite.yaml
View file

@ -200,9 +200,9 @@ paths:
Notifies the server that a third party identifier has been bound to one
of its users.
description: |-
Used by Identity Servers to notify the homeserver that one of its users
Used by Identity Services to notify the homeserver that one of its users
has bound a third party identifier successfully, including any pending
room invites the Identity Server has been made aware of.
room invites the Identity Service has been made aware of.
operationId: onBindThirdPartyIdentifier
parameters:
- in: body
@ -262,9 +262,9 @@ paths:
# also make sure it isn't lying about anything, like the key version
signed:
type: object
title: Identity Server Signatures
title: Identity Service Signatures
description: |-
Signature from the Identity Server using a long-term private
Signature from the Identity Service using a long-term private
key.
properties:
mxid:
@ -280,14 +280,14 @@ paths:
example: "Hello World"
signatures:
type: object
title: Identity Server Signature
title: Identity Service Signature
description: |-
The signature from the identity server. The ``string`` key
is the identity server's domain name, such as vector.im
The signature from the identity service. The ``string`` key
is the identity service's domain name, such as vector.im
additionalProperties:
type: object
title: Identity Server Domain Signature
description: The signature for the identity server.
title: Identity Service Domain Signature
description: The signature for the identity service.
properties:
"ed25519:0":
type: string

2
changelogs/client_server.rst
View file

@ -76,7 +76,7 @@ r0.3.0
- Spec clarifications:
- Add endpoints and logic for invites and third-party invites to the federation
spec and update the JSON of the request sent by the identity server upon 3PID
spec and update the JSON of the request sent by the identity service upon 3PID
binding
(`#997 <https://github.com/matrix-org/matrix-doc/pull/997>`_)
- Fix "membership" property on third-party invite upgrade example

16
meta/documentation_style.rst
View file

@ -69,10 +69,10 @@ have English as their first language.
Prefer British English (colour, -ise) to American English.
The word "homeserver" is spelt thus (rather than "home server", "Homeserver",
or (argh) "Home Server"). However, an identity server is two words.
or (argh) "Home Server"). However, an identity service is two words.
.. Rationale: "homeserver" distinguishes from a "home server" which is a server
you have at home. "Identity server" is clear, whereas "identityserver" is
.. Rationale: "homeserver" distinguishes from a "home server" which is a server
you have at home. "Identity Service" is clear, whereas "identityservice" is
horrible.
Lists should:
@ -91,9 +91,9 @@ When writing OpenAPI specifications for the API endpoints, follow these rules:
* ``description``: a longer description of the behaviour of this API, written
in complete sentences. Use multiple paragraphs if necessary.
Example:
Example:
This API sends an event to the room. The server must ensure that the user
has permission to post events to this room.
@ -106,7 +106,7 @@ When writing OpenAPI specifications for the API endpoints, follow these rules:
The description is also the place to define default values for optional
properties. Use the wording "Defaults to X [if unspecified]."
Some descriptions start with the word "Optional" to explicitly mark optional
Some descriptions start with the word "Optional" to explicitly mark optional
properties and parameters. This is redundant. Instead, use the ``required``
property to mark those that are required.

4
meta/releasing_a_spec.md
View file

@ -1,7 +1,7 @@
# How to release a specification
There are several specifications that belong to matrix, such as the client-server
specification, server-server specification, and identity server specification. Each
specification, server-server specification, and identity service specification. Each
of these gets released independently of each other with their own version numbers.
Once a specification is ready for release, a branch should be created to track the
@ -34,7 +34,7 @@ The remainder of the process is as follows:
### Creating a release for a brand-new specification
Some specifications may not have ever had a release, and therefore need a bit more work
to become ready.
to become ready.
1. Activate your Python 3 virtual environment.
1. Having checked out the new release branch, navigate your way over to `./changelogs`.

14
specification/client_server_api.rst
View file

@ -145,7 +145,7 @@ Some requests have unique error codes:
Sent when a threepid given to an API cannot be used because no record matching the threepid was found.
:``M_SERVER_NOT_TRUSTED``:
The client's request used a third party server, eg. ID server, that this server does not trust.
The client's request used a third party server, eg. identity service, that this server does not trust.
:``M_UNSUPPORTED_ROOM_VERSION``:
The client's request to create a room used a room version that the server does not support.
@ -257,7 +257,7 @@ specify parameter values. The flow for this method is as follows:
points to a valid homeserver.
f. If the ``m.identity_server`` property is present, extract the
``base_url`` value for use as the base URL of the identity server.
``base_url`` value for use as the base URL of the identity service.
Validation for this URL is done as in the step above, but using
``/_matrix/identity/api/v1`` as the endpoint to connect to. If the
``m.identity_server`` property is present, but does not have a
@ -685,7 +685,7 @@ the auth code. Homeservers can choose any path for the ``redirect URI``. Once
the OAuth flow has completed, the client retries the request with the session
only, as above.
Email-based (identity server)
Email-based (identity service)
<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
:Type:
``m.login.email.identity``
@ -705,9 +705,9 @@ To use this authentication type, clients should submit an auth dict as follows:
"type": "m.login.email.identity",
"threepidCreds": [
{
"sid": "<identity server session id>",
"client_secret": "<identity server client secret>",
"id_server": "<url of identity server authed with, e.g. 'matrix.org:8090'>"
"sid": "<identity service session id>",
"client_secret": "<identity service client secret>",
"id_server": "<url of identity service authed with, e.g. 'matrix.org:8090'>"
}
],
"session": "<session ID>"
@ -995,7 +995,7 @@ Adding Account Administrative Contact Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A homeserver may keep some contact information for administrative use.
This is independent of any information kept by any Identity Servers.
This is independent of any information kept by any Identity Services.
{{administrative_contact_cs_http_api}}

4
specification/index.rst
View file

@ -107,7 +107,7 @@ The functionality that Matrix provides includes:
- Managing user accounts (registration, login, logout)
- Use of 3rd Party IDs (3PIDs) such as email addresses, phone numbers,
Facebook accounts to authenticate, identify and discover users on Matrix.
- Trusted federation of Identity servers for:
- Trusted federation of Identity Services for:
+ Publishing user public keys for PKI
+ Mapping of 3PIDs to Matrix IDs
@ -386,7 +386,7 @@ network accounts and phone numbers to their user ID. Linking 3PIDs creates a
mapping from a 3PID to a user ID. This mapping can then be used by Matrix
users in order to discover the user IDs of their contacts.
In order to ensure that the mapping from 3PID to user ID is genuine, a globally
federated cluster of trusted "Identity Servers" (IS) are used to verify the 3PID
federated cluster of trusted "Identity Services" (IS) are used to verify the 3PID
and persist and replicate the mappings.
Usage of an IS is not required in order for a client application to be part of

36
specification/modules/third_party_invites.rst
View file

@ -24,14 +24,14 @@ There are two flows here; one if a Matrix user ID is known for the third party
identifier, and one if not. Either way, the client calls ``/invite`` with the
details of the third party identifier.
The homeserver asks the identity server whether a Matrix user ID is known for
The homeserver asks the identity service whether a Matrix user ID is known for
that identifier:
- If it is, an invite is simply issued for that user.
- If it is not, the homeserver asks the identity server to record the details of
- If it is not, the homeserver asks the identity service to record the details of
the invitation, and to notify the invitee's homeserver of this pending invitation if it gets
a binding for this identifier in the future. The identity server returns a token
a binding for this identifier in the future. The identity service returns a token
and public key to the inviting homeserver.
When the invitee's homeserver receives the notification of the binding, it
@ -57,7 +57,7 @@ Server behaviour
----------------
Upon receipt of an ``/invite``, the server is expected to look up the third party
identifier with the provided identity server. If the lookup yields a result for
identifier with the provided identity service. If the lookup yields a result for
a Matrix User ID then the normal invite process can be initiated. This process
ends up looking like this:
@ -87,7 +87,7 @@ ends up looking like this:
However, if the lookup does not yield a bound User ID, the homeserver must store
the invite on the identity server and emit a valid ``m.room.third_party_invite``
the invite on the identity service and emit a valid ``m.room.third_party_invite``
event to the room. This process ends up looking like this:
::
@ -125,7 +125,7 @@ All homeservers MUST verify the signature in the event's
``content.third_party_invite.signed`` object.
The third party user will then need to verify their identity, which results in
a call from the Identity Server to the homeserver that bound the third party
a call from the Identity Service to the homeserver that bound the third party
identifier to a user. The homeserver then exchanges the ``m.room.third_party_invite``
event in the room for a complete ``m.room.member`` event for ``membership: invite``
for the user that has bound the third party identifier.
@ -142,7 +142,7 @@ the room. They may, however, indicate to their clients that a member's
membership is questionable.
For example, given H1, H2, and H3 as homeservers, UserA as a user of H1, and an
identity server IS, the full sequence for a third party invite would look like
identity service IS, the full sequence for a third party invite would look like
the following. This diagram assumes H1 and H2 are residents of the room while
H3 is attempting to join.
@ -207,15 +207,15 @@ H3 is attempting to join.
Note that when H1 sends the ``m.room.member`` event to H2 and H3 it does not
have to block on either server's receipt of the event. Likewise, H1 may complete
the ``/exchange_third_party_invite/:roomId`` request at the same time as sending
the ``m.room.member`` event to H2 and H3. Additionally, H3 may complete the
the ``m.room.member`` event to H2 and H3. Additionally, H3 may complete the
``/3pid/onbind`` request it got from IS at any time - the completion is not shown
in the diagram.
H1 MUST verify the request from H3 to ensure the ``signed`` property is correct
as well as the ``key_validity_url`` as still being valid. This is done by making
a request to the `Identity Server /isvalid`_ endpoint, using the provided URL
a request to the `Identity Service /isvalid`_ endpoint, using the provided URL
rather than constructing a new one. The query string and response for the provided
URL must match the Identity Server specification.
URL must match the Identity Service specification.
The reason that no other homeserver may reject the event based on checking
``key_validity_url`` is that we must ensure event acceptance is deterministic.
@ -236,22 +236,22 @@ ID and a third party identifier is hard. In particular, being able to look up
all third party identifiers from a matrix user ID (and accordingly, being able
to link each third party identifier) should be avoided wherever possible.
To this end, the third party identifier is not put in any event, rather an
opaque display name provided by the identity server is put into the events.
opaque display name provided by the identity service is put into the events.
Clients should not remember or display third party identifiers from invites,
other than for the use of the inviter themself.
Homeservers are not required to trust any particular identity server(s). It is
generally a client's responsibility to decide which identity servers it trusts,
not a homeserver's. Accordingly, this API takes identity servers as input from
Homeservers are not required to trust any particular identity service(s). It is
generally a client's responsibility to decide which identity services it trusts,
not a homeserver's. Accordingly, this API takes identity services as input from
end users, and doesn't have any specific trusted set. It is possible some
homeservers may want to supply defaults, or reject some identity servers for
*its* users, but no homeserver is allowed to dictate which identity servers
homeservers may want to supply defaults, or reject some identity services for
*its* users, but no homeserver is allowed to dictate which identity services
*other* homeservers' users trust.
There is some risk of denial of service attacks by flooding homeservers or
identity servers with many requests, or much state to store. Defending against
identity services with many requests, or much state to store. Defending against
these is left to the implementer's discretion.
.. _`Identity Server /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid
.. _`Identity Service /isvalid`: ../identity_service/unstable.html#get-matrix-identity-api-v1-pubkey-isvalid

20
specification/server_server_api.rst
View file

@ -844,35 +844,35 @@ When an user wants to invite another user in a room but doesn't know the Matrix
ID to invite, they can do so using a third-party identifier (e.g. an e-mail or a
phone number).
This identifier and its bindings to Matrix IDs are verified by an identity server
This identifier and its bindings to Matrix IDs are verified by an identity service
implementing the `Identity Service API`_.
Cases where an association exists for a third-party identifier
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the third-party identifier is already bound to a Matrix ID, a lookup request
on the identity server will return it. The invite is then processed by the inviting
on the identity service will return it. The invite is then processed by the inviting
homeserver as a standard ``m.room.member`` invite event. This is the simplest case.
Cases where an association doesn't exist for a third-party identifier
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If the third-party identifier isn't bound to any Matrix ID, the inviting
homeserver will request the identity server to store an invite for this identifier
homeserver will request the identity service to store an invite for this identifier
and to deliver it to whoever binds it to its Matrix ID. It will also send a
``m.room.third_party_invite`` event in the room to specify a display name, a token
and public keys the identity server provided as a response to the invite storage
and public keys the identity service provided as a response to the invite storage
request.
When a third-party identifier with pending invites gets bound to a Matrix ID,
the identity server will send a POST request to the ID's homeserver as described
the identity service will send a POST request to the ID's homeserver as described
in the `Invitation Storage`_ section of the Identity Service API.
The following process applies for each invite sent by the identity server:
The following process applies for each invite sent by the identity service:
The invited homeserver will create a ``m.room.member`` invite event containing
a special ``third_party_invite`` section containing the token and a signed object,
both provided by the identity server.
both provided by the identity service.
If the invited homeserver is in the room the invite came from, it can auth the
event and send it.
@ -894,14 +894,14 @@ server.
To do so, it will fetch from the room's state events the ``m.room.third_party_invite``
event for which the state key matches with the value for the ``token`` key in the
``third_party_invite`` object from the ``m.room.member`` event's content to fetch the
public keys initially delivered by the identity server that stored the invite.
public keys initially delivered by the identity service that stored the invite.
It will then use these keys to verify that the ``signed`` object (in the
``third_party_invite`` object from the ``m.room.member`` event's content) was
signed by the same identity server.
signed by the same identity service.
Since this ``signed`` object can only be delivered once in the POST request
emitted by the identity server upon binding between the third-party identifier
emitted by the identity service upon binding between the third-party identifier
and the Matrix ID, and contains the invited user's Matrix ID and the token
delivered when the invite was stored, this verification will prove that the
``m.room.member`` invite event comes from the user owning the invited third-party