From ed21f50cc328b9e45651f645453178c4b00670bd Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 23 Apr 2015 15:04:22 +0100 Subject: [PATCH 1/4] Add version 2 of the server key distribution API --- specification/30_server_server_api.rst | 134 +++++++++++++++++++++++++ 1 file changed, 134 insertions(+) diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst index db5bdcdc..8f3c7b0f 100644 --- a/specification/30_server_server_api.rst +++ b/specification/30_server_server_api.rst @@ -70,6 +70,140 @@ endpoints or to failover to another endpoint if an endpoint fails. Retrieving Server Keys ~~~~~~~~~~~~~~~~~~~~~~ +Version 2 ++++++++++ + +Publishing Keys +_______________ + +Home servers publish the allowed TLS fingerprints and signing keys in a JSON +object at ``/_matrix/key/v2/server/${key_id}``. The response contains a list of +``verify_keys`` that are valid for signing federation requests made by the +server and for signing events. It contains a list of ``old_verify_keys`` +which are only valid for signing events. Finally the response contains a list +of TLS certificate fingerprints to validate any connection made to the server. + +A server may have multiple keys active at a given time. A server may have any +number of old keys. It is recommended that servers return a single JSON +response listing all of its keys whenever any ``key_id`` is requested to reduce +the number of round trips needed to discover the relevant keys for a server. +However a server may return a different responses for a different ``key_id``. + +The ``tls_certificates`` contain a list of hashes of the X.509 TLS certificates +currently used by the server. The list must include SHA-256 hashes for every +certificate currently in use by the server. These fingerprints are valid until +the millisecond POSIX timestamp in ``valid_until_ts``. + +The ``verify_keys`` can be used to sign requests and events made by the server +until the millisecond POSIX timestamp in ``valid_until_ts``. If a Home Server +receives an event with a ``origin_server_ts`` after the ``valid_until_ts`` then +it should request that ``key_id`` for the originating server to check whether +the key has expired. + +The ``old_verify_keys`` can be used to sign events with an ``origin_server_ts`` +before the ``expired_ts``. + +Intermediate servers should cache a response for half of its remaining life +time to avoid serving a stale response. Servers should avoid querying for +certificates more frequently than once an hour to avoid flooding a server +with requests. + +==================== =================== ====================================== + Key Type Description +==================== =================== ====================================== +``server_name`` String DNS name of the home server. +``verify_keys`` Object Public keys of the home server for + verifying digital signatures. +``old_verify_keys`` Object The public keys that the server used + to use and when it stopped using them. +``signatures`` Object Digital signatures for this object + signed using the ``verify_keys``. +``tls_fingerprints`` Array of Objects Hashes of X.509 TLS certificates used + by this this server encoded as base64. +``valid_until_ts`` Integer POSIX timestamp when the list of valid + keys should be refreshed. +==================== =================== ====================================== + + +.. code:: json + + { + "old_verify_keys": { + "ed25519:auto1": { + "expired_ts": 922834800000, + "key": "Base+64+Encoded+Old+Verify+Key" + } + }, + "server_name": "example.org", + "signatures": { + "example.org": { + "ed25519:auto2": "Base+64+Encoded+Signature" + } + }, + "tls_fingerprints": [ + { + "sha256": "Base+64+Encoded+SHA-256-Fingerprint" + } + ], + "valid_until_ts": 1052262000000, + "verify_keys": { + "ed25519:auto2": { + "key": "Base+64+Encoded+Signature+Verification+Key" + } + } + } + +Querying Keys Through Another Server +____________________________________ + +Servers may offer a query API ``_matrix/key/v2/query/`` for getting the keys +for another server. This API can be used to GET at list of JSON objects for a +given server or to POST a bulk query for a number of keys from a number of +servers. Either way the response is a list of JSON objects containing the +JSON published by the server under ``_matrix/key/v2/server/`` signed by +both the originating server and by this server. + +This API can return keys for servers that are offline be using cached responses +taken from when the server was online. Keys can be queried from multiple +servers to mitigate against DNS spoofing. + +Requests: + +.. code:: + + GET /_matrix/key/v2/query/${server_name}/${key_id} HTTP/1.1 + + POST /_matrix/key/v2/query HTTP/1.1 + Content-Type: application/json + + { + "server_keys": { + "$server_name": [ + "$key_id" + ] + } + } + + +Response: + +.. code:: + + HTTP/1.1 200 OK + Content-Type: application/json + { + "server_keys": [ + # List of responses with same format as /_matrix/key/v2/server + # signed by both the originating server and this server. + ] + } + +Version 1 ++++++++++ +.. WARNING:: + Version 1 of key distribution is obsolete + + Home servers publish their TLS certificates and signing keys in a JSON object at ``/_matrix/key/v1``. From 4422e9ca2b7db4b2914d088ab754a89f4b822b76 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 23 Apr 2015 15:30:57 +0100 Subject: [PATCH 2/4] Add a short summary of how the v2 key api is supposed to be used --- specification/30_server_server_api.rst | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst index 8f3c7b0f..23e304fa 100644 --- a/specification/30_server_server_api.rst +++ b/specification/30_server_server_api.rst @@ -73,6 +73,14 @@ Retrieving Server Keys Version 2 +++++++++ +Each home server publishes its public keys under ``/_matrix/key/v2/server/``. +Home servers query for keys by either getting ``/_matrix/key/v2/server/`` +directly or by querying an intermediate perspective server using a +``/_matrix/key/v2/query`` API. Intermediate perspective servers query the +``/_matrix/key/v2/server/`` API on behalf of another server and sign the +response with their own key. A server may query multiple perspective servers +to ensure that they all report the same public keys. + Publishing Keys _______________ @@ -103,10 +111,10 @@ the key has expired. The ``old_verify_keys`` can be used to sign events with an ``origin_server_ts`` before the ``expired_ts``. -Intermediate servers should cache a response for half of its remaining life -time to avoid serving a stale response. Servers should avoid querying for -certificates more frequently than once an hour to avoid flooding a server -with requests. +Intermediate perspective servers should cache a response for half of its +remaining life time to avoid serving a stale response. Servers should avoid +querying for certificates more frequently than once an hour to avoid flooding +a server with requests. ==================== =================== ====================================== Key Type Description From 0db31821591093bbbe61984e0db7c526f37ab039 Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 23 Apr 2015 15:32:58 +0100 Subject: [PATCH 3/4] Describe what the expired_ts is --- specification/30_server_server_api.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst index 23e304fa..6217c294 100644 --- a/specification/30_server_server_api.rst +++ b/specification/30_server_server_api.rst @@ -109,7 +109,8 @@ it should request that ``key_id`` for the originating server to check whether the key has expired. The ``old_verify_keys`` can be used to sign events with an ``origin_server_ts`` -before the ``expired_ts``. +before the ``expired_ts``. The ``expired_ts`` is a millisecond POSIX timestamp +of when the originating server stopped using that key. Intermediate perspective servers should cache a response for half of its remaining life time to avoid serving a stale response. Servers should avoid From 6f269890be4dd2a4637a57fd4b6ecd39a5096e0d Mon Sep 17 00:00:00 2001 From: Mark Haines Date: Thu, 23 Apr 2015 16:06:07 +0100 Subject: [PATCH 4/4] Add a brief reference to the perspectives project and mention what should happen if a server goes offline --- specification/30_server_server_api.rst | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/specification/30_server_server_api.rst b/specification/30_server_server_api.rst index 6217c294..d9ce9611 100644 --- a/specification/30_server_server_api.rst +++ b/specification/30_server_server_api.rst @@ -81,6 +81,13 @@ directly or by querying an intermediate perspective server using a response with their own key. A server may query multiple perspective servers to ensure that they all report the same public keys. +This approach is borrowed from the Perspectives Project +(http://perspectives-project.org/), but modified to include the NACL keys and to +use JSON instead of XML. It has the advantage of avoiding a single trust-root +since each server is free to pick which perspective servers they trust and can +corroborate the keys returned by a given perspective server by querying other +servers. + Publishing Keys _______________ @@ -117,6 +124,10 @@ remaining life time to avoid serving a stale response. Servers should avoid querying for certificates more frequently than once an hour to avoid flooding a server with requests. +If a server goes offline intermediate perspective servers should continue to +return the last response they received from that server so that the signatures +of old events sent by that server can still be checked. + ==================== =================== ====================================== Key Type Description ==================== =================== ======================================