more docstring for the e2e_room_keys rest

This commit is contained in:
Matthew Hodgson 2017-12-24 17:42:17 +00:00 committed by Hubert Chathi
parent 8d14598e90
commit 9f500cb39e
2 changed files with 51 additions and 2 deletions

View File

@ -59,7 +59,6 @@ class E2eRoomKeysHandler(object):
@defer.inlineCallbacks @defer.inlineCallbacks
def upload_room_keys(self, user_id, version, room_keys): def upload_room_keys(self, user_id, version, room_keys):
# TODO: Validate the JSON to make sure it has the right keys. # TODO: Validate the JSON to make sure it has the right keys.
# XXX: perhaps we should use a finer grained lock here? # XXX: perhaps we should use a finer grained lock here?
@ -139,7 +138,6 @@ class E2eRoomKeysHandler(object):
@defer.inlineCallbacks @defer.inlineCallbacks
def create_version(self, user_id, version_info): def create_version(self, user_id, version_info):
# TODO: Validate the JSON to make sure it has the right keys. # TODO: Validate the JSON to make sure it has the right keys.
# lock everyone out until we've switched version # lock everyone out until we've switched version

View File

@ -208,6 +208,10 @@ class RoomKeysServlet(RestServlet):
""" """
Deletes one or more encrypted E2E room keys for a user for backup purposes. Deletes one or more encrypted E2E room keys for a user for backup purposes.
DELETE /room_keys/keys/!abc:matrix.org/c0ff33?version=1
HTTP/1.1 200 OK
{}
room_id: the ID of the room whose keys to delete (optional) room_id: the ID of the room whose keys to delete (optional)
session_id: the ID for the E2E session to delete (optional) session_id: the ID for the E2E session to delete (optional)
version: the version of the user's backup which this data is for. version: the version of the user's backup which this data is for.
@ -240,6 +244,33 @@ class RoomKeysVersionServlet(RestServlet):
@defer.inlineCallbacks @defer.inlineCallbacks
def on_POST(self, request, version): def on_POST(self, request, version):
"""
Create a new backup version for this user's room_keys with the given
info. The version is allocated by the server and returned to the user
in the response. This API is intended to be used whenever the user
changes the encryption key for their backups, ensuring that backups
encrypted with different keys don't collide.
The algorithm passed in the version info is a reverse-DNS namespaced
identifier to describe the format of the encrypted backupped keys.
The auth_data is { user_id: "user_id", nonce: <random string> }
encrypted using the algorithm and current encryption key described above.
POST /room_keys/version
Content-Type: application/json
{
"algorithm": "m.megolm_backup.v1",
"auth_data": "dGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgZW5jcnlwdGVkIGpzb24K"
}
HTTP/1.1 200 OK
Content-Type: application/json
{
"version": 12345
}
"""
if version: if version:
raise SynapseError(405, "Cannot POST to a specific version") raise SynapseError(405, "Cannot POST to a specific version")
@ -257,6 +288,17 @@ class RoomKeysVersionServlet(RestServlet):
@defer.inlineCallbacks @defer.inlineCallbacks
def on_GET(self, request, version): def on_GET(self, request, version):
"""
Retrieve the version information about a given version of the user's
room_keys backup.
GET /room_keys/version/12345 HTTP/1.1
{
"algorithm": "m.megolm_backup.v1",
"auth_data": "dGhpcyBzaG91bGQgYWN0dWFsbHkgYmUgZW5jcnlwdGVkIGpzb24K"
}
"""
requester = yield self.auth.get_user_by_req(request, allow_guest=False) requester = yield self.auth.get_user_by_req(request, allow_guest=False)
user_id = requester.user.to_string() user_id = requester.user.to_string()
@ -267,6 +309,15 @@ class RoomKeysVersionServlet(RestServlet):
@defer.inlineCallbacks @defer.inlineCallbacks
def on_DELETE(self, request, version): def on_DELETE(self, request, version):
"""
Delete the information about a given version of the user's
room_keys backup. Doesn't delete the actual room data.
DELETE /room_keys/version/12345 HTTP/1.1
HTTP/1.1 200 OK
{}
"""
requester = yield self.auth.get_user_by_req(request, allow_guest=False) requester = yield self.auth.get_user_by_req(request, allow_guest=False)
user_id = requester.user.to_string() user_id = requester.user.to_string()