Clarify the distinction between *m.key.verification.start* and its *m.sas.v1* variant. #2132
Conversation
jimmycuadra
changed the title
….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 protected]>
Signed-off-by: Jimmy Cuadra <[email protected]>
|
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.
|
Okay, I think I've addressed all feedback. Ready for another review. |
|
It looks like I'm unable to commit the changelog change myself, but this PR looks good to go once the changelog is addressed. Thank you! |
3 participants
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:
next_methodfield to the schema of the m.sas.v1 variant, as specified in the general form of m.key.verification.start.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 [email protected]