Engage Advertising And Discovery - rallytac/pub GitHub Wiki

UNDER CONSTRUCTION

Engage supports a variety of methods for advertising and discovery and cover a broad range of implementations, use-cases, and technologies.

Engine Advertising

If enabled, Engage Engines advertise their presence on the network and participation in groups through a variety of protocols. Fundementally, though, the intention is that entities on the network - be they other Engage Engines, Rallypoints, or third-party applications and services - can discover Engage Engines and take action accordingly.

The simplest advertising methodology followed by Engage is to use a combination of Session Anouncement Protocol (SAP) and SDP (Session Description Protocol). In Engage's implementation, we encapsulate SDP inside SAP packets - a common approach in the industry - to convey group session information on multicast networks. You can find more information about SAP and SDP on Wikipedia: SAP, and SDP.

If we were to examine a multicasted UDP packet transmitted by an Engage Engine, it may look as follows (from a Wireshark capture):

Frame 2374: 623 bytes on wire (4984 bits), 623 bytes captured (4984 bits) on interface 0
Ethernet II, Src: Apple_ca:b5:35 (8c:85:90:ca:b5:35), Dst: IPv4mcast_02:7f:fe (01:00:5e:02:7f:fe)
Internet Protocol Version 4, Src: 192.168.1.234, Dst: 224.2.127.254
User Datagram Protocol, Src Port: 9875, Dst Port: 9875
Session Announcement Protocol
    Flags: 0x20
    Authentication Length: 0
    Message Identifier Hash: 0xbe99
    Originating Source: 224.2.127.254
    Payload type: application/vnd.rallytac.eap
Session Description Protocol
    Time Description, active time (t): 0 0
    Session Attribute (a): tool:Engage Engine 1.91.8847
    Session Attribute (a): engagenode:{c779621c-a967-4de8-8d40-2a67843f543b}
    Session Attribute (a): engagegroup:{770bc400-a0ea-4e7e-a624-20e2b6d2706b} 1 234.42.42.1 18000
    Session Attribute (a): engagegroup:{91220ae4-b610-4295-9db0-ec648b36f362} 1 234.42.42.4 18006
    Session Attribute (a): engagegroup:{9d4c3587-f736-455c-83ab-19c7169c1228} 1 234.42.42.2 18002
    Session Attribute (a): engagegroup:{e7280f07-6712-463f-a811-cc3ed4128cd9} 1 234.42.42.3 18004 232.7.7.19 21000
    Session Attribute (a): engagegroup:{ead2d373-7bca-472c-8732-7e1c27a69b27} 2 234.42.42.99 19999
    Session Attribute (a): engagedigest:081977D8B9217E677863B6E62929441749393E8C193C84FFCF46E47586975B13

The two areas we're most interested in is "Session Announcement Protocol" and "Session Description Protocol".

Session Announcement Protocol

  • flags, Authentication Length, and Message Identifier Hash are outlined in the standard and won't be discussed here.
  • Payload type is a string describing the SDP payload that follows. For advertisements from Engage entities (Engines and Rallypoints), this string is "application/vnd.rallytac.eap".

Session Description Protocol

The SDP portion of the packet consists of a mandatory time field (t), along with a number of attribute (a) fields that convey information being advertised. These attribute fields are in the format a=<attribute_name>:<attribute_value>.

  • Time Description, active time (t) is the starting and ending time of the session. As we don't really have a "session" here, but rather descriptions of one or more sessions, both the starting and end times are set to 0. There is only one "t" field.

  • Session Attribute (a): tool is a string representing the "tool" that is making the advertisement. In this case it is an Engage Engine with a version number of 1.91.8847. There is only one "a=tool" field.

  • Session Attribute (a): engagenode is a string containing the GUID of the advertising entity. In this case it is the unique Engage Engine identifier. There is only one "a=engagenode" field.

  • Session Attribute (a): engagegroup describes a single Engage Group being advertised. It is in the format of "<group_id> <group_type> <rx_address> <rx_port> <tx_address> <tx_port>" where "<tx_address>" and "<tx_port>" are omitted if they are the same as "<rx_address>" and "<rx_port>". In the example provided, each group has the same TX address and port as its corresponding RX address and port; except for the group identified by "{e7280f07-6712-463f-a811-cc3ed4128cd9}" - which has has a different TX configuration that it's RX configuration. The "<group_type>" field indicates what type of traffic the group transports: Type 1 is a RTP audio group, type 2 is a JSON-based Engage Presence group, and type 3 is a so-called "raw" group - one that Engage provides to the user application to do with as it pleases. Data format and content is undefined for raw groups.

  • Session Attribute (a): engagedigest is a SHA-256 hash of the contents of the SDP payload (excluding "engagedigest") combined with an internal salt embedded into Engage Engines and Rallypoints. While not a signficant source of protection against attacks, this field serves to provide a measure of confidence in the SDP payload content. The hash is calculated across all fields of the SDP in the order of their appearance excluding newline characters and, of course, the digest field itself. Please note that the hash in the example is not representative of the values in the example as content and order of the lines have been altered for purposes of readabilty.

⚠️ **GitHub.com Fallback** ⚠️