diff --git a/api/identity/pubkey.yaml b/api/identity/pubkey.yaml new file mode 100644 index 00000000..48a091d1 --- /dev/null +++ b/api/identity/pubkey.yaml @@ -0,0 +1,97 @@ +swagger: '2.0' +info: + title: "Matrix Identity Service Public Key API" + version: "1.0.0" +host: localhost:8090 +schemes: + - https + - http +basePath: /_matrix/identity/v1/api +produces: + - application/json +paths: + "/pubkey/{keyId}": + get: + summary: Get a public key. + description: |- + Get the public key for the passed key ID. + parameters: + - in: path + type: string + name: keyId + required: true + description: |- + The ID of the key. This should take the form algorithm:identifier + where algorithm identifies the signing algorithm, and the identifier + is an opaque string. + x-example: "ed25519:0" + responses: + 200: + description: + The public key exists. + examples: + application/json: |- + { + "public_key": "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + } + schema: + type: object + properties: + public_key: + type: string + "/pubkey/isvalid": + get: + summary: Check whether a long-term public key is valid. + description: |- + Check whether a long-term public key is valid. + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: |- + { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. + "/pubkey/ephemeral/isvalid": + get: + summary: Check whether a short-term public key is valid. + description: |- + Check whether a short-term public key is valid. + parameters: + - in: query + type: string + name: public_key + required: true + description: |- + The unpadded base64-encoded public key to check. + x-example: "VXuGitF39UH5iRfvbIknlvlAVKgD1BsLDMvBf0pmp7c" + responses: + 200: + description: + The validity of the public key. + examples: + application/json: |- + { + "valid": true + } + schema: + type: object + properties: + valid: + type: boolean + description: Whether the public key is recognised and is currently valid. diff --git a/specification/identity_service_api.rst b/specification/identity_service_api.rst new file mode 100644 index 00000000..7308a562 --- /dev/null +++ b/specification/identity_service_api.rst @@ -0,0 +1,60 @@ +Identity Service API +==================== + +The Matrix client-server and server-server APIs are largely expressed in Matrix +user identifiers. From time to time, it is useful to refer to users by other +("third-party") identifiers, or "3pid"s, e.g. their email address or phone +number. This identity service specification describes how mappings between +third-party identifiers and Matrix user identifiers can be established, +verified, and used. + +.. contents:: Table of Contents +.. sectnum:: + +General principles +------------------ + +The purpose of an identity service is to verify, store, and answer questions +about the identities of users. In particular, it stores associations of the form +"identifier X represents the same user as identifier Y", where identities may +exist on different systems (such as email addresses, phone numbers, +Matrix user IDs, etc). + +The identity service has some private-public keypairs. When asked about an +association, it will sign details of the association with its private key. +Clients may verify the assertions about associations by verifying the signature +with the public key of the identity service. + +In general, identity services are treated as reliable oracles. They do not +necessarily provide evidence that they have verified associations, but claim to +have done so. Establishing the trustworthiness of an individual identity service +is left as an exercise for the client. + +Privacy +------- + +Identity is a privacy-sensitive issue. While the identity service exists to +provide identity information, access should be restricted to avoid leaking +potentially sensitive data. In particular, being able to construct large-scale +connections between identities should be avoided. To this end, in general APIs +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). + +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 +TODO: link. + +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 +keypairs, which may have different usage and lifetime characteristics than the +service's long-term keys. + +{{pubkey_is_http_api}} diff --git a/specification/index.rst b/specification/index.rst index b65b45c6..eb2e3287 100644 --- a/specification/index.rst +++ b/specification/index.rst @@ -19,6 +19,7 @@ The following APIs are documented in this specification: - `Client-Server API `_ version %CLIENT_RELEASE_LABEL% for writing Matrix clients. - `Server-Server API `_ version %SERVER_RELEASE_LABEL% for writing servers which can federate with Matrix. - `Application Service API `_ version %CLIENT_RELEASE_LABEL% for writing privileged plugins to servers. +- `Identity Service API `_ version unstable for mapping third party identifiers (e.g. email addresses) to Matrix IDs. There are also some `appendices `_. diff --git a/specification/targets.yaml b/specification/targets.yaml index bf2d8f11..40a8e07f 100644 --- a/specification/targets.yaml +++ b/specification/targets.yaml @@ -19,6 +19,9 @@ targets: files: - server_server_api.rst - { 1: event_signing.rst } + identity_service: + files: + - identity_service_api.rst appendices: files: - appendices.rst diff --git a/templating/matrix_templates/units.py b/templating/matrix_templates/units.py index 726d9169..2ad0a9b6 100644 --- a/templating/matrix_templates/units.py +++ b/templating/matrix_templates/units.py @@ -20,6 +20,7 @@ import yaml HTTP_APIS = { "../api/application-service": "as", "../api/client-server": "cs", + "../api/identity": "is", } EVENT_EXAMPLES = "../event-schemas/examples" EVENT_SCHEMA = "../event-schemas/schema"