From 10c3307427808da03aed24165b17c4911486b3b0 Mon Sep 17 00:00:00 2001
From: Valentin Deniaud <valentin.deniaud@inpt.fr>
Date: Mon, 11 Jun 2018 15:18:59 +0200
Subject: [PATCH] document device_one_time_keys_count in /sync/ response

fix #1157
---
 api/client-server/sync.yaml                     |  8 ++++++++
 specification/modules/end_to_end_encryption.rst | 11 +++++++++++
 2 files changed, 19 insertions(+)

diff --git a/api/client-server/sync.yaml b/api/client-server/sync.yaml
index 34659dd0..4b44c20e 100644
--- a/api/client-server/sync.yaml
+++ b/api/client-server/sync.yaml
@@ -253,6 +253,14 @@ paths:
                 description: |-
                   Information on end-to-end device updates, as specified in
                   |device_lists_sync|_.
+              device_one_time_keys_count:
+                title: One-time keys count
+                type: object
+                additionalProperties:
+                  type: integer
+                description: |-
+                  Information on end-to-end encryption keys, as specified
+                  in |device_lists_sync|_.
           examples:
             application/json: {
                 "next_batch": "s72595_4483_1934",
diff --git a/specification/modules/end_to_end_encryption.rst b/specification/modules/end_to_end_encryption.rst
index 68e030e1..b030ab64 100644
--- a/specification/modules/end_to_end_encryption.rst
+++ b/specification/modules/end_to_end_encryption.rst
@@ -355,6 +355,9 @@ specified). The client is expected to use |/keys/query|_ or |/keys/changes|_
 for the equivalent functionality after an initial sync, as documented in
 `Tracking the device list for a user`_.
 
+It also adds a ``one_time_keys_count`` property. Note the spelling difference
+with the ``one_time_key_counts`` property in the |/keys/upload|_ response.
+
 .. todo: generate this from a swagger definition?
 
 .. device_lists: { changed: ["@user:server", ... ]},
@@ -364,6 +367,9 @@ Parameter    Type        Description
 ============ =========== =====================================================
 device_lists DeviceLists Optional. Information on e2e device updates. Note:
                          only present on an incremental sync.
+|device_otk| {string:    Optional. For each key algorithm, the number of
+             integer}    unclaimed one-time keys currently held on the server
+                         for this device.
 ============ =========== =====================================================
 
 ``DeviceLists``
@@ -388,6 +394,10 @@ Example response:
          "@alice:example.com",
       ],
     },
+    "device_one_time_keys_count": {
+      "curve25519": 10,
+      "signed_curve25519": 20
+    }
   }
 
 .. References
@@ -400,6 +410,7 @@ Example response:
 .. _`Signing JSON`: ../appendices.html#signing-json
 
 .. |m.olm.v1.curve25519-aes-sha2| replace:: ``m.olm.v1.curve25519-aes-sha2``
+.. |device_otk| replace:: device_one_time_keys_count
 
 .. |/keys/upload| replace:: ``/keys/upload``
 .. _/keys/upload: #post-matrix-client-%CLIENT_MAJOR_VERSION%-keys-upload