Daniel Wagner-Hall
8 years ago
committed by
review.rocks
parent
446ad008be
commit
e0c55eeccf
@ -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