Document chain_index in the m.room_key content

[mujx]

Example of an m.room_key event received in the to_device messages. This the decrypted value of the body parameter of a m.room.encrypted event with algorithm m.olm.v1.curve25519-aes-sha2.

{
  "content": {
    "algorithm": "m.megolm.v1.aes-sha2",
    "chain_index": 1,
    "room_id": "!zjgktONDKMCjaeudxB:matrix.org",
    "session_id": "2OniRbRNPsPtzkHPsGd2tJWnlpdcHEX4sB5A+NNJsKE",
    "session_key": "AgAAAAGj1yy98su6O5tDw5MAkMpZPcMtiDbIvY2J6z1D......"
  },
  "keys": {
    "ed25519": "L5IUXmjZGzZO9IwB/j61lTjuD79TCMRDM4bBHvGstT4"
  },
  "recipient": "@test:matrix.org",
  "recipient_keys": {
    "ed25519": "9DjH9K2Ig15EpQht6llFXpD0GKs2r3E6CRuHbHEljaA"
  },
  "sender": "@test:matrix.org",
  "sender_device": "VVLXGGTJGN",
  "type": "m.room_key"
}

[richvdh]

part of #501

[Zil0]

Tried to track this one down and I can find where it is added to the event in the JS SDK code, but not where it is used. Also, I think it was added in a pretty old commit matrix-org/matrix-js-sdk@89d8133#diff-024555cb57c92e1a32d639aab9f8cde3R451. Could it be just a legacy field?

[richvdh]

Have just tried to remember what is going on here, and:

Could it be just a legacy field?

yes, it is.

Background: the megolm ratchet key increments with each message, and each message has an index which tells you how far you need to advance the ratchet, in case you miss any messages. When you receive a new ratchet key, it's possible that it is not starting at index 0, so you need to know the index it does start at. This is the chain_index, and previously it was transmitted as shown here, out-of-band.

However, the chain_index is now included in the serialised format of the ratchet key, so there is no need for it to be sent out of band. (The relevant change to the olm library is https://git.matrix.org/git/olm/commit/?id=e0b5197). When we made this change, we kept sending the chain_index out of band for older clients. It should probably now be removed from the js-sdk; either way, there is no need for it to be sent by new clients.

[Zil0]

Thanks for the explanation! Shouldn't this be closed then?

[richvdh]

probably!