Merge pull request #293 from matrix-org/daniel/is
Add initial identity server spec More to comepull/977/head
commit
7868fb1a08
@ -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.
|
@ -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}}
|
Loading…
Reference in New Issue