diff --git a/api/identity/associations.yaml b/api/identity/associations.yaml new file mode 100644 index 00000000..784bb5d6 --- /dev/null +++ b/api/identity/associations.yaml @@ -0,0 +1,179 @@ +# 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. +# 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. +swagger: '2.0' +info: + title: "Matrix Identity Service Establishing Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https + - http +basePath: /_matrix/identity/api/v1 +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 + operationId: getValidated3pid + parameters: + - in: query + type: string + name: sid + description: The Session ID generated by the ``requestToken`` call. + required: true + x-example: 1234 + - in: query + type: string + name: client_secret + description: The client secret passed to the ``requestToken`` call. + required: true + x-example: monkeys_are_GREAT + responses: + 200: + description: Validation information for the session. + examples: + application/json: { + "medium": "email", + "validated_at": 1457622739026, + "address": "louise@bobs.burgers" + } + schema: + type: object + properties: + medium: + type: string + description: The medium type of the 3pid. + address: + type: string + description: The address of the 3pid being looked up. + validated_at: + type: integer + description: Timestamp indicating the time that the 3pid was validated. + 400: + description: |- + The session has not been validated. + + If the session has not been validated, then ``errcode`` will be + ``M_SESSION_NOT_VALIDATED``. If the session has timed out, then + ``errcode`` will be ``M_SESSION_EXPIRED``. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + 404: + description: The Session ID or client secret were not found + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } + "/bind": + post: + summary: Publish an association between a session and a Matrix user ID. + description: |- + Publish an association between a session and a Matrix user ID. + + Future calls to ``/lookup`` for any of the session\'s 3pids will return + this association. + + Note: for backwards compatibility with older versions of this + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: bind + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "mxid": "@ears:matrix.org" + } + properties: + sid: + type: string + description: The Session ID generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret passed to the ``requestToken`` call. + mxid: + type: string + description: The Matrix user ID to associate with the 3pids. + required: ["sid", "client_secret", "mxid"] + responses: + 200: + description: The association was published. + examples: + application/json: { + "address": "louise@bobs.burgers", + "medium": "email", + "mxid": "@ears:matrix.org", + "not_before": 1428825849161, + "not_after": 4582425849161, + "ts": 1428825849161, + + "signatures": { + "matrix.org": { + "ed25519:0": "ENiU2YORYUJgE6WBMitU0mppbQjidDLanAusj8XS2nVRHPu+0t42OKA/r6zV6i2MzUbNQ3c3MiLScJuSsOiVDQ" + } + } + } + schema: + type: object + properties: + address: + type: string + description: The 3pid address of the user being looked up. + medium: + type: string + description: The medium type of the 3pid. + mxid: + type: string + description: The Matrix user ID associated with the 3pid. + not_before: + type: integer + description: A unix timestamp before which the association is not known to be valid. + not_after: + type: integer + description: A unix timestamp after which the association is not known to be valid. + ts: + type: integer + 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. + 400: + description: |- + The association was not published. + + If the session has not been validated, then ``errcode`` will be + ``M_SESSION_NOT_VALIDATED``. If the session has timed out, then + ``errcode`` will be ``M_SESSION_EXPIRED``. + examples: + application/json: { + "errcode": "M_SESSION_NOT_VALIDATED", + "error": "This validation session has not yet been completed" + } + 404: + description: The Session ID or client secret were not found + examples: + application/json: { + "errcode": "M_NO_VALID_SESSION", + "error": "No valid session was found matching that sid and client secret" + } diff --git a/api/identity/email_associations.yaml b/api/identity/email_associations.yaml new file mode 100644 index 00000000..8431c9e8 --- /dev/null +++ b/api/identity/email_associations.yaml @@ -0,0 +1,197 @@ +# 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. +# 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. +swagger: '2.0' +info: + title: "Matrix Identity Service Email Associations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https + - http +basePath: /_matrix/identity/api/v1 +produces: + - application/json +paths: + "/validate/email/requestToken": + post: + summary: Request a token for validating an email address. + description: |- + Create a session for validating an email address. + + The identity service will send an email containing a token. If that + token is presented to the identity service in the future, it indicates + 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 + 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 + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: emailRequestToken + parameters: + - in: body + name: body + schema: + type: object + example: { + "client_secret": "monkeys_are_GREAT", + "email": "foo@example.com", + "send_attempt": 1 + } + properties: + client_secret: + type: string + description: A unique string used to identify the validation attempt + email: + type: string + description: The email address to validate. + send_attempt: + type: integer + description: |- + Optional. If specified, the server will only send an email if + the ``send_attempt`` is a number greater than the most recent + one which it has seen (or if it has never seen one), scoped + to that ``email`` + ``client_secret`` pair. This is to avoid + repeatedly sending the same email in the case of request + retries between the POSTing user and the identity + service. The client should increment this value if they + desire a new email (e.g. a reminder) to be sent. + next_link: + type: string + description: |- + Optional. When the validation is completed, the identity + service will redirect the user to this URL. + required: ["client_secret", "email"] + responses: + 200: + description: + Session created. + examples: + application/json: { + "sid": "1234" + } + schema: + type: object + properties: + sid: + type: string + description: The session ID. + 400: + description: | + An error ocurred. Some possible errors are: + + - ``M_INVALID_EMAIL``: The email address provided was invalid. + - ``M_EMAIL_SEND_ERROR``: The validation email could not be sent. + "/validate/email/submitToken": + post: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + 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 + specification, the parameters may also be specified as + ``application/x-form-www-urlencoded`` data. However, this usage is + deprecated. + operationId: emailSubmitTokenPost + parameters: + - in: body + name: body + schema: + type: object + example: { + "sid": "1234", + "client_secret": "monkeys_are_GREAT", + "token": "atoken" + } + properties: + sid: + type: string + description: The session ID, generated by the ``requestToken`` call. + client_secret: + type: string + description: The client secret that was supplied to the ``requestToken`` call. + token: + type: string + description: The token generated by the ``requestToken`` call and emailed to the user. + required: ["sid", "client_secret", "token"] + responses: + 200: + description: + The success of the validation. + examples: + application/json: { + "success": true + } + schema: + type: object + properties: + success: + type: boolean + description: Whether the validation was successful or not. + get: + summary: Validate ownership of an email address. + description: |- + Validate ownership of an email address. + + If the three parameters are consistent with a set generated by a + ``requestToken`` call, ownership of the email address is considered to + have been validated. This does not publish any information publicly, or + associate the email address with any Matrix user ID. Specifically, + calls to ``/lookup`` will not show a binding. + + Note that, in contrast with the POST version, this endpoint will be + used by end-users, and so the response should be human-readable. + operationId: emailSubmitTokenGet + parameters: + - in: query + type: string + name: sid + required: true + description: The session ID, generated by the ``requestToken`` call. + x-example: 1234 + - in: query + type: string + name: client_secret + required: true + description: The client secret that was supplied to the ``requestToken`` call. + x-example: monkeys_are_GREAT + - in: query + type: string + name: token + required: true + description: The token generated by the ``requestToken`` call and emailed to the user. + x-example: atoken + responses: + "200": + description: Email address is validated. + "3xx": + description: |- + Email address is validated, and the ``next_link`` parameter was + provided to the ``requestToken`` call. The user must be redirected + to the URL provided by the ``next_link`` parameter. + "4xx": + description: + Validation failed. diff --git a/api/identity/invitation_signing.yaml b/api/identity/invitation_signing.yaml new file mode 100644 index 00000000..982dbff7 --- /dev/null +++ b/api/identity/invitation_signing.yaml @@ -0,0 +1,90 @@ +# 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. +# 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. +swagger: '2.0' +info: + title: "Matrix Identity Service Ephemeral Invitation Signing API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https + - http +basePath: /_matrix/identity/api/v1 +produces: + - application/json +paths: + "/sign-ed25519": + post: + summary: Sign invitation details + description: |- + Sign invitation details. + + The identity server will look up ``token`` which was stored in a call + to ``store-invite``, and fetch the sender of the invite. + operationId: blindlySignStuff + parameters: + - in: body + name: body + schema: + type: object + example: { + "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`` + 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. + schema: + type: object + properties: + mxid: + type: string + description: The Matrix user ID of the user accepting the invitation. + sender: + type: string + description: The Matrix user ID of the user who sent the invitation. + signatures: + type: object + description: The signature of the mxid, sender, and token. + token: + type: string + description: The token for the invitation. + examples: + application/json: { + "mxid": "@foo:bar.com", + "sender": "@baz:bar.com", + "signatures": { + "my.id.server": { + "ed25519:0": "def987" + } + }, + "token": "abc123" + } + 404: + description: Token was not found. + example: { + "errcode": "M_UNRECOGNIZED", + "error": "Didn't recognize token" + } diff --git a/api/identity/store_invite.yaml b/api/identity/store_invite.yaml new file mode 100644 index 00000000..6b847b5b --- /dev/null +++ b/api/identity/store_invite.yaml @@ -0,0 +1,114 @@ +# 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. +# 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. +swagger: '2.0' +info: + title: "Matrix Identity Service Store Invitations API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https + - http +basePath: /_matrix/identity/api/v1 +produces: + - application/json +paths: + "/store-invite": + post: + summary: Store pending invitations to a user\'s 3pid. + description: |- + 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 + the invite message generation described below. + + The service will generate a random token and an ephemeral key used for + accepting the invite. + + The service also generates a ``display_name`` for the inviter, which is + a redacted version of ``address`` which does not leak the full contents + of the ``address``. + + The service records persistently all of the above information. + + It also generates an email containing all of this data, sent to the + ``address`` parameter, notifying them of the invitation. + + Also, the generated ephemeral public key will be listed as valid on + requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. + operationId: storeInvite + parameters: + - in: body + name: body + schema: + type: object + example: { + "medium": "email", + "address": "foo@bar.baz", + "room_id": "!something:example.tld", + "sender": "@bob:example.com" + } + properties: + medium: + type: string + description: The literal string ``email``. + address: + type: string + description: The email address of the invited user. + room_id: + type: string + description: The Matrix room ID to which the user is invited + sender: + type: string + description: The Matrix user ID of the inviting user + required: ["medium", "address", "room_id", "sender"] + responses: + 200: + description: The invitation was stored. + schema: + type: object + properties: + token: + type: string + description: The generated token. + public_keys: + type: array + description: A list of [server\'s long-term public key, generated ephemeral public key]. + items: + type: string + display_name: + type: string + description: The generated (redacted) display_name. + example: + application/json: { + "token": "sometoken", + "public_keys": [ + "serverpublickey", + "ephemeralpublickey" + ], + "display_name": "f...@b..." + } + 400: + description: | + An error has occured. + + If the 3pid is already bound to a Matrix user ID, the error code + will be ``M_THREEPID_IN_USE``. If the medium is unsupported, the + error code will be ``M_UNRECOGNIZED``. + examples: + application/json: { + "errcode": "M_THREEPID_IN_USE", + "error": "Binding already known", + "mxid": mxid + } diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst index 89fcc3e6..cb079593 100644 --- a/specification/identity_service_api.rst +++ b/specification/identity_service_api.rst @@ -114,100 +114,15 @@ 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. -Creating a session +Email associations ~~~~~~~~~~~~~~~~~~ -A client makes a call to:: +{{email_associations_is_http_api}} - POST https://my.id.server:8090/_matrix/identity/api/v1/validate/email/requestToken +General +~~~~~~~ - client_secret=monkeys_are_GREAT& - email=foo@bar.com& - send_attempt=1 - -It may also optionally specify next_link. If next_link is specified, when the -validation is completed, the identity service will redirect the user to that -URL. - -This will create a new "session" on the identity service, identified by an -``sid``. - -The identity service will send an email containing a token. If that token is -presented to the identity service in the future, it indicates that that user was -able to read the email for that email address, and so we validate ownership of -the email address. - -We return the ``sid`` generated for this session to the caller, in a JSON object -containing the ``sid`` key. - -If a send_attempt is specified, the server will only send an email if the -send_attempt is a number greater than the most recent one which it has seen (or -if it has never seen one), scoped to that email address + client_secret pair. -This is to avoid repeatedly sending the same email in the case of request -retries between the POSTing user and the identity service. The client should -increment this value if they desire a new email (e.g. a reminder) to be sent. - -Note that Home Servers 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. - -Validating ownership of an email -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A user may make either a ``GET`` or a ``POST`` request to -``/_matrix/identity/api/v1/validate/email/submitToken`` with the following -parameters (either as query parameters or URL-encoded POST parameters): -- ``sid`` the sid for the session, generated by the ``requestToken`` call. -- ``client_secret`` the client secret which was supplied to the ``requestToken`` call. -- ``token`` the token generated by the ``requestToken`` call, and emailed to the user. - -If these three values are consistent with a set generated by a ``requestToken`` -call, ownership of the email address is considered to have been validated. This -does not publish any information publicly, or associate the email address with -any Matrix user ID. Specifically, calls to ``/lookup`` will not show a binding. - -Otherwise, an error will be returned. - -Checking non-published 3pid ownership -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -A client can check whether ownership of a 3pid was validated by making an -HTTP GET request to ``/_matrix/identity/api/v1/3pid/getValidated3pid``, passing -the ``sid`` and ``client_secret`` as query parameters from the ``requestToken`` -call. - -It will return something of either the form:: - - {"medium": "email", "validated_at": 1457622739026, "address": "foo@bar.com"} - -or:: - - {"errcode": "M_SESSION_NOT_VALIDATED", "error": "This validation session has not yet been completed"} - -If the ``sid`` and ``client_secret`` were not recognised, or were not correct, -an error will be returned. - -Publishing a validated association -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An association between a session and a Matrix user ID can be published by making -a URL-encoded HTTP POST request to ``/_matrix/identity/api/v1/3pid/bind`` with -the following parameters:: - - sid=sid& - client_secret=monkeys_are_GREAT& - mxid=@foo:bar.com - -If the session is still valid, this will publish an association between the -3pids validated on that session and the passed Matrix user ID. Future calls -to ``/lookup`` for any of the session's 3pids will return this association. - -If the 3pid has not yet been validated, the HTTP request will be rejected, and -the association will not be established. - -If the ``sid`` and ``client_secret`` were not recognised, or were not correct, -an error will be returned. +{{associations_is_http_api}} Invitation Storage ------------------ @@ -216,32 +131,6 @@ 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. -If one makes a ``POST`` request to ``/_matrix/identity/api/v1/store-invite`` with the following URL-encoded POST parameters: - -- ``medium`` (string, required): The literal string ``email``. -- ``address`` (string, required): The email address of the invited user. -- ``room_id`` (string, required): The Matrix room ID to which the user is invited. -- ``sender`` (string, required): The matrix user ID of the inviting user. - -An arbitrary number of other parameters may also be specified. These may be used in the email generation described below. - -The service will look up whether the 3pid is bound to a Matrix user ID. If it is, the request will be rejected with a 400 status code. - -If the medium is something other than the literal string ``email``, the request will be rejected with a 400 status code. - -Otherwise, the service will then generate a random string called ``token``, and an ephemeral public key. - -The service also generates a ``display_name`` for the inviter, which is a redacted version of ``address`` which does not leak the full contents of the ``address``. - -The service records persistently all of the above information. - -It also generates an email containing all of this data, sent to the ``address`` parameter, notifying them of the invitation. - -The response body is then populated as the JSON-encoded dictionary containing the following fields: -- ``token`` (string): The generated token. -- ``public_keys`` ([string]): A list of [server's long-term public key, generated ephemeral public key]. -- ``display_name`` (string): The generated (redacted) display_name. - 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 @@ -273,7 +162,7 @@ At a later point, if the owner of that particular 3pid binds it with a Matrix us Where the signature is produced using a long-term private key. -Also, the generated ephemeral public key will be listed as valid on requests to ``/_matrix/identity/api/v1/pubkey/ephemeral/isvalid``. +{{store_invite_is_http_api}} Ephemeral invitation signing ---------------------------- @@ -281,23 +170,7 @@ 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. -The identity service will happily sign invitation details with a request-specified ed25519 private key for you, if you want it to. It takes URL-encoded POST parameters: -- mxid (string, required) -- token (string, required) -- private_key (string, required): The private key, encoded as `Unpadded base64`_. - -It will look up ``token`` which was stored in a call to ``store-invite``, and fetch the sender of the invite. It will then respond with JSON which looks something like:: - - { - "mxid": "@foo:bar.com", - "sender": "@baz:bar.com", - "signatures" { - "my.id.server": { - "ed25519:0": "def987" - } - }, - "token": "abc123" - } +{{invitation_signing_is_http_api}} .. _`Unpadded Base64`: ../appendices.html#unpadded-base64 .. _`3PID Types`: ../appendices.html#pid-types