Ensures scope has a group session and shares it with userIds' known
devices -- the prerequisite encryptEvent documents for itself: a scope
must have a group session before encryption can succeed. Not a change to
the frozen surface; a new public name for what the core calls
share_scope_key, chosen to say what it does without naming an
algorithm (design doc section 3bis / spec section 6).
Delivering a key to a device with no prior session takes two calls to
this function, not one -- design doc section 3ter, and the ordering is
not optional. A device this machine has never shared with has no Olm
session yet, and a session key can only reach a device over one; that
needs a /keys/claim round trip first. So the first call to
shareScopeKey for a new device queues a 'keys_claim' request (among
takeOutgoingRequests' output) alongside a to-device request that
cannot yet carry the key -- it is an m.room_key.withheld notice, not
the key itself. Only once the product has sent that claim and reported
it with markRequestSent does calling shareScopeKeyagain,
for the same scope and users, produce the to-device request that
actually carries the session key. The full sequence, per device:
shareScopeKey (queues 'keys_claim', if no session yet)
send the 'keys_claim' request, markRequestSent it
shareScopeKey again, same scope and users (now produces the
key-carrying 'to_device' request)
send that request, markRequestSent it
A product that calls this once, sends what takeOutgoingRequests
returns, and moves on silently under-delivers to every device it has not
already shared with -- the same silent-failure shape design doc section
3bis is named for, one step further in. receiveSyncChanges (which
queues the 'keys_query' step that must come before either of the above,
so this machine knows the device exists at all) and this function
together are what section 3ter's ordering describes.
Ensures
scopehas a group session and shares it withuserIds' known devices -- the prerequisiteencryptEventdocuments for itself: a scope must have a group session before encryption can succeed. Not a change to the frozen surface; a new public name for what the core callsshare_scope_key, chosen to say what it does without naming an algorithm (design doc section 3bis / spec section 6).Delivering a key to a device with no prior session takes two calls to this function, not one -- design doc section 3ter, and the ordering is not optional. A device this machine has never shared with has no Olm session yet, and a session key can only reach a device over one; that needs a
/keys/claimround trip first. So the first call toshareScopeKeyfor a new device queues a'keys_claim'request (among takeOutgoingRequests' output) alongside a to-device request that cannot yet carry the key -- it is anm.room_key.withheldnotice, not the key itself. Only once the product has sent that claim and reported it with markRequestSent does callingshareScopeKeyagain, for the same scope and users, produce the to-device request that actually carries the session key. The full sequence, per device:shareScopeKey(queues'keys_claim', if no session yet)'keys_claim'request,markRequestSentitshareScopeKeyagain, same scope and users (now produces the key-carrying'to_device'request)markRequestSentitA product that calls this once, sends what takeOutgoingRequests returns, and moves on silently under-delivers to every device it has not already shared with -- the same silent-failure shape design doc section 3bis is named for, one step further in.
receiveSyncChanges(which queues the'keys_query'step that must come before either of the above, so this machine knows the device exists at all) and this function together are what section 3ter's ordering describes.