diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml index 4225919b..a400bf95 100644 --- a/api/identity/associations.yaml +++ b/api/identity/associations.yaml @@ -18,15 +18,17 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: "/3pid/getValidated3pid": get: summary: Check whether ownership of a 3pid was validated. - description: A client can check whether ownership of a 3pid was validated + description: |- + Determines if a given 3pid has been validated by a user. operationId: getValidated3pid parameters: - in: query @@ -61,7 +63,9 @@ paths: description: The address of the 3pid being looked up. validated_at: type: integer - description: Timestamp indicating the time that the 3pid was validated. + description: |- + Timestamp, in milliseconds, indicating the time that the 3pid + was validated. required: ['medium', 'address', 'validated_at'] 400: description: |- @@ -78,7 +82,7 @@ paths: schema: $ref: "../client-server/definitions/errors/error.yaml" 404: - description: The Session ID or client secret were not found + description: The Session ID or client secret were not found. examples: application/json: { "errcode": "M_NO_VALID_SESSION", @@ -95,7 +99,7 @@ paths: Future calls to ``/lookup`` for any of the session\'s 3pids will return this association. - Note: for backwards compatibility with older versions of this + 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 deprecated. @@ -132,7 +136,6 @@ paths: "not_before": 1428825849161, "not_after": 4582425849161, "ts": 1428825849161, - "signatures": { "matrix.org": { "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" @@ -162,7 +165,10 @@ paths: description: The unix timestamp at which the association was verified. signatures: type: object - description: The signatures of the verifying identity services which show that the association should be trusted, if you trust the verifying identity services. + description: |- + The signatures of the verifying identity services which show that the + association should be trusted, if you trust the verifying identity + services. $ref: "../../schemas/server-signatures.yaml" required: - address diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml index 28f5e680..dc3cd78e 100644 --- a/api/identity/email_associations.yaml +++ b/api/identity/email_associations.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -34,13 +35,13 @@ paths: that that user was able to read the email for that email address, and so we validate ownership of the email address. - Note that Home Servers offer APIs that proxy this API, adding + Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, ``/register/email/requestToken`` is designed specifically for use when registering an account and therefore will inform the user if the email address given is already registered on the server. - Note: for backwards compatibility with older versions of this + 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 deprecated. @@ -58,7 +59,7 @@ paths: properties: client_secret: type: string - description: A unique string used to identify the validation attempt + description: A unique string used to identify the validation attempt. email: type: string description: The email address to validate. @@ -119,7 +120,7 @@ paths: associate the email address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - Note: for backwards compatibility with older versions of this + 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 deprecated. diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml index 7de62dd4..0b76a773 100644 --- a/api/identity/invitation_signing.yaml +++ b/api/identity/invitation_signing.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -29,7 +30,7 @@ paths: description: |- Sign invitation details. - The identity server will look up ``token`` which was stored in a call + The identity service will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. operationId: blindlySignStuff parameters: @@ -38,24 +39,24 @@ paths: schema: type: object example: { - "mxid": "@foo:bar.com", - "token": "sometoken", - "private_key": "base64encodedkey" - } + "mxid": "@foo:bar.com", + "token": "sometoken", + "private_key": "base64encodedkey" + } properties: mxid: type: string description: The Matrix user ID of the user accepting the invitation. token: type: string - description: Token from the call to ``store-invite`` + description: The token from the call to ``store-invite``. private_key: type: string description: The private key, encoded as `Unpadded base64`_. required: ["mxid", "token", "private_key"] responses: 200: - description: The signedjson of the mxid, sender, and token. + description: The signed JSON of the mxid, sender, and token. schema: type: object properties: @@ -85,7 +86,7 @@ paths: "token": "abc123" } 404: - description: Token was not found. + description: The token was not found. examples: application/json: { "errcode": "M_UNRECOGNIZED", diff --git a/api/identity/lookup.yaml b/api/identity/lookup.yaml index f04436ef..1870a31f 100644 --- a/api/identity/lookup.yaml +++ b/api/identity/lookup.yaml @@ -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. @@ -20,8 +21,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -46,7 +48,7 @@ paths: responses: 200: description: - The association for that 3pid, or the empty object if no association is known. + The association for that 3pid, or an empty object if no association is known. examples: application/json: { "address": "louise@bobs.burgers", @@ -66,10 +68,10 @@ paths: properties: address: type: string - description: The 3pid address of the user being looked up. + description: The 3pid address of the user being looked up, matching the address requested. medium: type: string - description: The literal string "email". + description: A medium from the `3PID Types`_ Appendix, matching the medium requested. mxid: type: string description: The Matrix user ID associated with the 3pid. @@ -126,7 +128,9 @@ paths: #- type: 3PID Address - type: string - type: string - description: an array of arrays containing the `3PID Types`_ with the ``medium`` in first position and the ``address`` in second position. + description: |- + An array of arrays containing the `3PID Types`_ with the ``medium`` + in first position and the ``address`` in second position. required: - "threepids" responses: @@ -157,6 +161,9 @@ paths: - type: string - type: string - type: string - description: an array of array containing the `3PID Types`_ with the ``medium`` in first position, the ``address`` in second position and Matrix ID in third position. + description: |- + An array of array containing the `3PID Types`_ with the ``medium`` + in first position, the ``address`` in second position and Matrix user + ID in third position. required: - "threepids" diff --git a/api/identity/phone_associations.yaml b/api/identity/phone_associations.yaml index f6b1bd45..836984d0 100644 --- a/api/identity/phone_associations.yaml +++ b/api/identity/phone_associations.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -34,13 +35,13 @@ paths: indicates that that user was able to read the SMS for that phone number, and so we validate ownership of the phone number. - Note that Home Servers offer APIs that proxy this API, adding + Note that homeservers offer APIs that proxy this API, adding additional behaviour on top, for example, ``/register/msisdn/requestToken`` is designed specifically for use when registering an account and therefore will inform the user if the phone number given is already registered on the server. - Note: for backwards compatibility with older versions of this + 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 deprecated. @@ -106,6 +107,8 @@ paths: - ``M_INVALID_ADDRESS``: The phone number provided was invalid. - ``M_SEND_ERROR``: The validation SMS could not be sent. + - ``M_DESTINATION_REJECTED``: The identity service cannot deliver an + SMS to the provided country or region. examples: application/json: { "errcode": "M_INVALID_ADDRESS", @@ -125,7 +128,7 @@ paths: associate the phone number address with any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - Note: for backwards compatibility with older versions of this + 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 deprecated. diff --git a/api/identity/ping.yaml b/api/identity/ping.yaml index 005160a3..2788d9d3 100644 --- a/api/identity/ping.yaml +++ b/api/identity/ping.yaml @@ -1,4 +1,5 @@ # Copyright 2018 Kamax Sàrl +# 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. @@ -14,7 +15,7 @@ swagger: "2.0" info: - title: "Matrix Client-Identity Versions API" + title: "Matrix Identity Service Ping API" version: "1.0.0" host: localhost:8090 schemes: @@ -25,19 +26,19 @@ produces: paths: "/api/v1": get: - summary: Checks that an Identity server is available at this API endpopint. + summary: Checks that an Identity Service is available at this API endpoint. description: |- - Checks that an Identity server is available at this API endpopint. + Checks that an Identity Service is available at this API endpoint. - To discover that an Identity server is available at a specific URL, + To discover that an Identity Service is available at a specific URL, this endpoint can be queried and will return an empty object. This is primarly used for auto-discovery and health check purposes - by entities acting as a client for the Identity server. + by entities acting as a client for the Identity Service. operationId: ping responses: 200: - description: An Identity server is ready to serve requests. + description: An Identity Service is ready to serve requests. examples: application/json: {} schema: diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml index 9cb7c74e..6b17e7c6 100644 --- a/api/identity/pubkey.yaml +++ b/api/identity/pubkey.yaml @@ -18,8 +18,9 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: @@ -113,8 +114,8 @@ paths: The validity of the public key. examples: application/json: { - "valid": true - } + "valid": true + } schema: type: object properties: diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml index 1eca7198..89d437a4 100644 --- a/api/identity/store_invite.yaml +++ b/api/identity/store_invite.yaml @@ -18,16 +18,17 @@ info: host: localhost:8090 schemes: - https - - http basePath: /_matrix/identity/api/v1 +consumes: + - application/json produces: - application/json paths: "/store-invite": post: - summary: Store pending invitations to a user\'s 3pid. + summary: Store pending invitations to a user's 3pid. description: |- - Store pending invitations to a user\'s 3pid. + Store pending invitations to a user's 3pid. In addition to the request parameters specified below, an arbitrary number of other parameters may also be specified. These may be used in @@ -47,6 +48,8 @@ paths: Also, the generated ephemeral public key will be listed as valid on requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + + Currently, invites may only be issued for 3pids of the ``email`` medium. operationId: storeInvite parameters: - in: body @@ -84,7 +87,7 @@ paths: description: The generated token. 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: @@ -111,7 +114,7 @@ paths: application/json: { "errcode": "M_THREEPID_IN_USE", "error": "Binding already known", - "mxid": mxid + "mxid": "@alice:example.com" } schema: $ref: "../client-server/definitions/errors/error.yaml" diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 7bbd8ae8..f6997ea1 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -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. @@ -56,7 +57,7 @@ is left as an exercise for the client. 3PID types are described in `3PID Types`_ Appendix. -API Standards +API standards ------------- The mandatory baseline for identity service communication in Matrix is exchanging @@ -136,6 +137,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 ------------ @@ -146,25 +163,24 @@ 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. In the event of key compromise, the identity service may revoke any of its keys. 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. @@ -183,6 +199,12 @@ 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 ~~~~~~~~~~~~~~~~~~ @@ -198,53 +220,31 @@ 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.html#put-matrix-federation-v1-3pid-onbind