Join GitHub today
GitHub is home to over 40 million developers working together to host and review code, manage projects, and build software together.Sign up
Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. #2132
Currently the m.key.verification.start event appears twice with the exact same title, in the "Key verification framework" section and the "Short Authentication (SAS) verification" section. It's not immediately clear that the first occurrence describes the format of the event in general terms and that the second occurrence describes the fields when the m.sas.v1 verification method is being used. This is a similar relationship to the m.room.message event and its various msgtype
This commit does three things:
Note: These changes are based on my intuition of what the intent was, but I might be completely wrong about any or all of this!
Signed-off-by: Jimmy Cuadra firstname.lastname@example.org
….sas.v1* variant. Currently the *m.key.verification.start* event appears twice with the exact same title, in the "Key verification framework" section and the "Short Authentication (SAS) verification" section. It's not immediately clear that the first occurrence describes the format of the event in general terms and that the second occurrence describes the fields when the *m.sas.v1* verification method is being used. This is a similar relationship to the *m.room.message* event and its various *msgtype* variants. This commit does three things: * It tweaks the generation of the documentation to change the title of the second occurrence of *m.key.verification.start* to distinguish it from the first. * It updates the language in the description of the two versions of the event to better describe the relationship between the two. * It adds the optional `next_method` field to the schema of the *m.sas.v1* variant, as specified in the general form of *m.key.verification.start*. Signed-off-by: Jimmy Cuadra <email@example.com>
Another issue related to this that I noticed is that m.key.verification.accept has equivalent fields to the m.sas.v1-specific version of m.key.verification.start. This makes me think that the accept event should have a "generic" form and method-specific forms just like the start event does. In other words, I think there ought to be separate "m.key.verification.accept" and "m.key.verification.accept (m.sas.v1)" sections to mirror the two already addressed in this PR. Or perhaps just adding "(m.sas.v1)" to the title of the current section without adding a "generic" version. Thoughts?
re: keeping the
It's a little confusing at the moment, however we anticipate other verification methods being introduced. The spec is built to support the future case, as hopefully it'll be near future rather than distant future.
* Switch "an SAS" back to "a SAS" * Remove the `next_method` field from m.key.verification.start$m.sas.v1 but add additional clarification to its description on m.key.verification.start that it is never present for methods that verify keys both ways.