initial spec for cross-signing

[uhoreg]

Spec PR for #1756

Does not have any mentions of SSSS, since that is not written up yet.

Rendered version of changes at

• Client-Server:
  • main cross-signing section (runs until "Sharing keys between devices" section)
  • additions to POST /keys/query
• Server-Server:
  • device management section (GET /user/devices and a little update to m.device_list_update)
    • example in Response for /user/devices (and in m.signing_key_update below) is messed up, and I don't know what I'm doing
  • end-to-end encryption section (POST /user/keys/query and m.signing_key_update schema)

[Sorunome]

Not sure which lines and thus don't know where to do line-comments on the PR, but in POST /_matrix/client/r0/keys/signatures/upload the section "Request format" says No parameters, while the text above lays out the map and the example request also contains said map.

[Sorunome]

Is there a way to only query the cross-signing keys? Is it sufficient to query only one device key of a user to them in the reply, or do you need to query all device keys of a user (empty list)?

[uhoreg]

No, there's no way to query just the cross-signing keys. Querying device is sufficient. The user's ID just needs to appear in the query.

[uhoreg]

Not sure which lines and thus don't know where to do line-comments on the PR, but in POST /_matrix/client/r0/keys/signatures/upload the section "Request format" says No parameters, while the text above lays out the map and the example request also contains said map.

Yes, that seems to just be the way our documentation generator works. On fact, the whole body is a parameter, but since it doesn't have any listed properties, the documentation generator thinks there's nothing there.

[babolivier]

As a comment that came out of matrix-org/synapse#7594, it's not super obvious that the USK is only used by its owner and isn't sent to other servers over federation (unlike the two other keys), maybe this could be detailed here?

[uhoreg]

As a comment that came out of matrix-org/synapse#7594, it's not super obvious that the USK is only used by its owner and isn't sent to other servers over federation (unlike the two other keys), maybe this could be detailed here?

Words (and diagram!) have been added that hopefully clarify this.

[richvdh]

generally looks great. a few bits and bobs.

[richvdh]

this isn't working in the rendered output, for some reason.

[uhoreg]

It's because our generator wants the body to have a fixed set of properties, rather than being a mapping of IDs, so I don't think this can be fixed without making changes to the build system.

[richvdh]

nor this

[uhoreg]

This looks fine to me

[richvdh]

lgtm!