Spec v5 rooms: Key validity

api/server-server/definitions/keys.yaml

@@ -94,6 +94,12 @@ properties:
     type: integer
     format: int64
     description: |-
-      POSIX timestamp when the list of valid keys should be refreshed. Keys used beyond this
-      timestamp are no longer valid.
+      POSIX timestamp when the list of valid keys should be refreshed. This field MUST
+      be ignored in room versions 1, 2, 3, and 4. Keys used beyond this timestamp MUST
+      be considered invalid, depending on the `room version specification`_.
+
+      Servers MUST use the lesser of this field and 7 days into the future when
+      determining if a key is valid. This is to avoid a situation where an attacker
+      publishes a key which is valid for a significant amount of time without a way
+      for the homeserver owner to revoke it.
     example: 1052262000000

changelogs/server_server/newsfragments/2080.clarification

@@ -0,0 +1 @@
+Clarify how ``valid_until_ts`` behaves with respect to room version.

specification/index.rst

@@ -494,6 +494,7 @@ The available room versions are:
 * `Version 2 <rooms/v2.html>`_ - **Stable**. Implements State Resolution Version 2.
 * `Version 3 <rooms/v3.html>`_ - **Stable**. Introduces events whose IDs are the event's hash.
 * `Version 4 <rooms/v4.html>`_ - **Stable**. Builds on v3 by using URL-safe base64 for event IDs.
+* `Version 5 <rooms/v5.html>`_ - **Stable**. Introduces enforcement of signing key validity periods.
 
 Specification Versions
 ----------------------

specification/rooms/v5.rst

@@ -0,0 +1,59 @@
+.. Copyright 2019 The Matrix.org Foundation C.I.C.
+..
+.. 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.
+
+Room Version 5
+==============
+
+This room version builds on `version 4 <v4.html>`_ while enforcing signing
+key validity periods for events.
+
+.. contents:: Table of Contents
+.. sectnum::
+
+
+Client considerations
+---------------------
+
+There are no specific requirements for clients in this room version. Clients should
+be aware of event ID changes in `room version 4 <v4.html>`_, however.
+
+
+Server implementation components
+--------------------------------
+
+.. WARNING::
+   The information contained in this section is strictly for server implementors.
+   Applications which use the Client-Server API are generally unaffected by the
+   intricacies contained here. The section above regarding client considerations
+   is the resource that Client-Server API use cases should reference.
+
+
+Room version 5 uses the same algorithms defined in `room version 4 <v4.html>`_, ensuring
+that signing key validity is respected.
+
+Signing key validity period
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When validating event signatures, servers MUST enforce the ``valid_until_ts`` property
+from a key request is at least as large as the ``origin_server_ts`` for the event being
+validated. Servers missing a copy of the signing key MUST try to obtain one via the
+`GET /_matrix/key/v2/server <../server_server/r0.1.1.html#get-matrix-key-v2-server-keyid>`_
+or `POST /_matrix/key/v2/query <../server_server/r0.1.1.html#post-matrix-key-v2-query>`_
+APIs. When using the ``/query`` endpoint, servers MUST set the ``minimum_valid_until_ts``
+property to prompt the notary server to attempt to refresh the key if appropriate.
+
+Servers MUST use the lesser of ``valid_until_ts`` and 7 days into the future when
+determining if a key is valid. This is to avoid a situation where an attacker
+publishes a key which is valid for a significant amount of time without a way for
+the homeserver owner to revoke it.

specification/targets.yaml

@@ -42,6 +42,10 @@ targets:
     files:
       - rooms/v4.rst
     version_label: v4
+  rooms@v5: # this is translated to be rooms/v5.html
+    files:
+      - rooms/v5.rst
+    version_label: v5
   appendices:
     files:
       - appendices.rst