From 37aa66b19b0cb76894755311107ffb889ccf11cb Mon Sep 17 00:00:00 2001 From: Jan Klass Date: Sat, 1 Feb 2025 14:52:19 +0100 Subject: [PATCH] DOCS(dev): Improve wording and formatting of network protocol docs Drop the 'unreliable' label from UDP. Delivery is not guaranteed, but delivery reliability largely depends on network context. Unreliable makes it sound more negative and error-prone than it is. We use UDP because and with the understanding that in most cases it is quite reliable, or reliable enough, rather than simply being unreliable. The point is that we use it for low-latency. Everything else is technical reasoning. Prefer short statement sentences over long comma sentences. 'an TLSv1 encrypted connection' -> 'a TLSv1 encrypted connection' Format message type name as inline code to indicate it being a "type" name. --- docs/dev/network-protocol/overview.md | 4 ++-- docs/dev/network-protocol/protocol_stack_tcp.md | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/dev/network-protocol/overview.md b/docs/dev/network-protocol/overview.md index 2454d197e6..3bbdf5c3ff 100644 --- a/docs/dev/network-protocol/overview.md +++ b/docs/dev/network-protocol/overview.md @@ -3,12 +3,12 @@ Mumble is based on a standard server-client communication model. It utilizes two channels of communication, the first one is a TCP connection which is used to reliably transfer control data between the client and the -server. The second one is a UDP connection which is used for unreliable, +server. The second one is a UDP connection which is used for low latency transfer of voice data. ![Mumble system overview](resources/mumble_system_overview.png) -Both are protected by strong cryptography, this encryption is mandatory and cannot be disabled. The TCP control channel uses TLSv1 AES256-SHA[^1] while the voice channel is encrypted with OCB-AES128[^2]. +Both are protected by strong cryptography. This encryption is mandatory and cannot be disabled. The TCP control channel uses TLSv1 AES256-SHA[^1] while the voice channel is encrypted with OCB-AES128[^2]. ![Mumble crypt types](resources/mumble_crypt_types.png) diff --git a/docs/dev/network-protocol/protocol_stack_tcp.md b/docs/dev/network-protocol/protocol_stack_tcp.md index f4694957d3..0b0c319e7c 100644 --- a/docs/dev/network-protocol/protocol_stack_tcp.md +++ b/docs/dev/network-protocol/protocol_stack_tcp.md @@ -2,7 +2,7 @@ Mumble has a shallow and easy to understand stack. Basically it uses Google's Protocol Buffers[^1] with simple prefixing to -distinguish the different kinds of packets sent through an TLSv1 +distinguish the different kinds of packets sent through a TLSv1 encrypted connection. This makes the protocol very easily expandable. ![resources/mumble_packet.png](Mumble packet) @@ -10,8 +10,8 @@ encrypted connection. This makes the protocol very easily expandable. The prefix consists out of the two bytes defining the type of the packet in the payload and 4 bytes stating the length of the payload in bytes followed by the payload itself. The following packet types are available -in the current protocol and all but UDPTunnel are simple protobuf messages. -If not mentioned otherwise all fields outside the protobuf encoding are big-endian. +in the current protocol and all but `UDPTunnel` are simple protobuf messages. +If not mentioned otherwise all fields outside the protobuf encoding are *big-endian*. | Type | Payload | | ---- | ------------------- |