From 2abbc647d7775ccfce1b3d268bb7f44146fe0539 Mon Sep 17 00:00:00 2001 From: David Baker Date: Wed, 3 May 2023 14:37:42 +0100 Subject: [PATCH] Add party_id --- .../client-server-api/modules/voip_events.md | 20 +++++++++++++++++++ data/event-schemas/schema/m.call.answer.yaml | 3 +++ .../schema/m.call.candidates.yaml | 3 +++ data/event-schemas/schema/m.call.hangup.yaml | 3 +++ data/event-schemas/schema/m.call.invite.yaml | 5 ++++- 5 files changed, 33 insertions(+), 1 deletion(-) diff --git a/content/client-server-api/modules/voip_events.md b/content/client-server-api/modules/voip_events.md index b877450d..8dbdaff4 100644 --- a/content/client-server-api/modules/voip_events.md +++ b/content/client-server-api/modules/voip_events.md @@ -21,6 +21,26 @@ backwards-compatible. If it does become necessary to introduce a non backwards-compatible VoIP spec, the intention would be for it to simply use a separate set of event types. +#### Party Identifiers +Whenever a client first participates in a new call, it generates a `party_id` for itself to use for the +duration of the call. This needs to be long enough that the chance of a collision between multiple devices +both generating an answer at the same time generating the same party ID is vanishingly small: 8 uppercase + +lowercase alphanumeric characters is recommended. Parties in the call are identified by the tuple of +`(user_id, party_id)`. + +The client adds a `party_id` field containing this ID to the top-level of the content of all VoIP events +it sends on the call, including `m.call.invite`. Clients use this to identify remote echo of their own +events: since a user may now call themselves, they can no longer ignore events from their own user. This +field also identifies different answers sent by different clients to an invite, and matches `m.call.candidates` +events to their respective answer/invite. + +A client implementation may choose to use the device ID used in end-to-end cryptography for this purpose, +or it may choose, for example, to use a different one for each call to avoid leaking information on which +devices were used in a call (in an unencrypted room) or if a single device (ie. access token) were used to +send signalling for more than one call party. + +A grammar for `party_id` is defined [below](#specify-exact-grammar-for-voip-ids). + #### Events {{% event-group group_name="m.call" %}} diff --git a/data/event-schemas/schema/m.call.answer.yaml b/data/event-schemas/schema/m.call.answer.yaml index ab68b3c9..08058aed 100644 --- a/data/event-schemas/schema/m.call.answer.yaml +++ b/data/event-schemas/schema/m.call.answer.yaml @@ -32,6 +32,9 @@ "version": { "type": "number", "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0" + }, + "party_id": { + "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. " } }, "required": ["call_id", "answer", "version"] diff --git a/data/event-schemas/schema/m.call.candidates.yaml b/data/event-schemas/schema/m.call.candidates.yaml index 3ad1b707..1ae83fca 100644 --- a/data/event-schemas/schema/m.call.candidates.yaml +++ b/data/event-schemas/schema/m.call.candidates.yaml @@ -35,6 +35,9 @@ "required": ["candidate", "sdpMLineIndex", "sdpMid"] } }, + "party_id": { + "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. " + }, "version": { "type": "integer", "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0." diff --git a/data/event-schemas/schema/m.call.hangup.yaml b/data/event-schemas/schema/m.call.hangup.yaml index bbcc8181..7342f133 100644 --- a/data/event-schemas/schema/m.call.hangup.yaml +++ b/data/event-schemas/schema/m.call.hangup.yaml @@ -16,6 +16,9 @@ "type": "integer", "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0." }, + "party_id": { + "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. " + }, "reason": { "type": "string", "description": "Optional error reason for the hangup. This should not be provided when the user naturally ends or rejects the call. When there was an error in the call negotiation, this should be `ice_failed` for when ICE negotiation fails or `invite_timeout` for when the other party did not answer in time.", diff --git a/data/event-schemas/schema/m.call.invite.yaml b/data/event-schemas/schema/m.call.invite.yaml index 2da045bd..bbfcbcda 100644 --- a/data/event-schemas/schema/m.call.invite.yaml +++ b/data/event-schemas/schema/m.call.invite.yaml @@ -33,6 +33,9 @@ "type": "string", "description": "The version of the VoIP specification this message adheres to. This specification is version 1. This field is a string such that experimental implementations can use non-integer versions. This field was an integer in the previous spec version and implementations must accept an integer 0." }, + "party_id": { + "This identifies the party that sent this event. A client may choose to re-use the device ID from end-to-end cryptography for the value of this field. " + }, "lifetime": { "type": "integer", "description": "The time in milliseconds that the invite is valid for. Once the invite age exceeds this value, clients should discard it. They should also no longer show the call as awaiting an answer in the UI." @@ -42,7 +45,7 @@ "description": "The ID of the user being called.", } }, - "required": ["call_id", "offer", "version", "lifetime"] + "required": ["call_id", "offer", "version", "lifetime", "party_id"] }, "type": { "type": "string",