Skip to content

Commit

Permalink
Merge PR #6715: DOCS(dev): Convert network protocol rst to md
Browse files Browse the repository at this point in the history 
Convert our network protocol docs from rst (ReStructuredText) to md (Markdown) format.

---

This changeset is a followup to PR #6623. In that PR, which first integrated these docs into this repository, the comments indicated consensus that the docs should be in Markdown format to match our other docs.

This changeset is based on PR #6714, which does some baseline corrections, and which should be merged first.

---

Two tables are not converted to Markdown tables because they are not flat tables, which is hard, if not impossible, to represent in Markdown. Preformatted code blocks are being used for them instead.

Otherwise, the conversion seems straightforward.

The changeset includes individual commits by change type, so each kind of change can be traced. The first commit is purely a rename to ensure Git follows the content history across the file conversion.
  • Loading branch information
@Kissaki
Kissaki authored Jan 27, 2025
2 parents 9d512e6 + b50ead3 commit 9e30471
Show file tree
Hide file tree
Showing 8 changed files with 537 additions and 745 deletions.
11 changes: 5 additions & 6 deletions docs/dev/network-protocol/README.rst → docs/dev/network-protocol/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,12 +1,11 @@
Mumble Network Protocol Documentation
=============================
# Mumble Network Protocol Documentation

The Mumble Network Protocol documentation is meant to be a reference for the
Mumble VoIP 1.2.X server-client communication protocol. It reflects the state of
the protocol implemented in the Mumble 1.2.8 client and might be outdated by the
time you are reading this.

* `Overview <overview.rst>`_
* `Protocol Stack (TCP) <protocol_stack_tcp.rst>`_
* `Establishing a Connection <establishing_connection.rst>`_
* `Voice Data <voice_data.rst>`_
* [Overview](overview.md)
* [Protocol Stack (TCP)](protocol_stack_tcp.md)
* [Establishing a Connection](establishing_connection.md)
* [Voice Data](voice_data.md)
161 changes: 161 additions & 0 deletions docs/dev/network-protocol/establishing_connection.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,161 @@
# Establishing a connection

This section describes the communication between the server and the client
during connection establishing, note that only the TCP connection needs
to be established for the client to be connected. After this the client
will be visible to the other clients on the server and able to send other
types of messages.

## Connect

As the basis for the synchronization procedure the client has to first
establish the TCP connection to the server and do a common TLSv1 handshake.
To be able to use the complete feature set of the Mumble protocol it is
recommended that the client provides a strong certificate to the server.
This however is not mandatory as you can connect to the server without
providing a certificate. However the server must provide the client with
its certificate and it is recommended that the client checks this.

![Mumble connection setup](resources/mumble_connection_setup.png)

## Version exchange

Once the TLS handshake is completed both sides should transmit their version
information using the Version message. The message structure is described below.

| Field | Type |
| ------------ | -------- |
| `version` | `uint32` |
| `release` | `string` |
| `os` | `string` |
| `os_version` | `string` |

The version field is a combination of major, minor and patch version numbers (e.g. 1.2.0)
so that major number takes two bytes and minor and patch numbers take one byte each.
The release, os and os_version
fields are common strings containing additional information.

| Major | Minor | Patch |
| ------- | ------ | ------ |
| 2 bytes | 1 byte | 1 byte |

The version information may be used as part of the *SuggestConfig* checks, which usually
refer to the standard client versions. The major changes between these versions are listed
in table below. The *release*, *os* and *os_version* information is not interpreted in
any way at the moment.

| Version | Major changes |
| ------- | ----------------------------------------- |
| 1.2.0 | CELT 0.7.0 codec support |
| 1.2.2 | CELT 0.7.1 codec support |
| 1.2.3 | CELT 0.11.0 codec |
| 1.2.4 | Opus codec support, SuggestConfig message |

## Authenticate

Once the client has sent the version it should follow this with the Authenticate message.
The message structure is described in the figure below. This message may be sent immediately
after sending the version message. The client does not need to wait for the server version
message.

| Field | Type |
| ---------- | -------- |
| `username` | `string` |
| `password` | `string` |
| `tokens` | `string` |

The username and password are UTF-8 encoded strings. While the client is free to accept any
username from the user the server is allowed to impose further restrictions. Furthermore
if the client certificate has been registered with the server the client is primarily
known with the username they had when the certificate was registered. For more
information see the server documentation.

The password must only be provided if the server is passworded, the client provided no
certificate but wants to authenticate to an account which has a password set, or to
access the SuperUser account.

The third field contains a list of zero or more token strings which act as passwords
that may give the client access to certain ACL groups without actually being a
registered member in them, again see the server documentation for more information.

## Crypto setup

Once the Version packets are exchanged the server will send a CryptSetup packet to
the client. It contains the necessary cryptographic information for the OCB-AES128
encryption used in the UDP Voice channel. The packet is described in figure
below. The encryption itself is described in a later section.

| Field | Type |
| -------------- | ----- |
| `key` | bytes |
| `client_nonce` | bytes |
| `server_nonce` | bytes |

## Channel states

After the client has successfully authenticated the server starts listing the channels
by transmitting partial ChannelState message for every channel on this server. These
messages lack the channel link information as the client does not yet have full
picture of all the channels. Once the initial ChannelState has been transmitted
for all channels the server updates the linked channels by sending new packets for
these. The full structure of these ChannelState messages is shown below:

| Field | Type |
| -------------- | ----------------- |
| `channel_id` | `uint32` |
| `parent` | `uint32` |
| `name` | `string` |
| `links` | repeated `uint32` |
| `description` | `string` |
| `links_add` | repeated `uint32` |
| `links_remove` | repeated `uint32` |
| `temporary` | optional `bool` |
| `position` | optional `int32` |

*The server must send a ChannelState for the root channel identified with ID 0.*

## User states

After the channels have been synchronized the server continues by listing the
connected users. This is done by sending a UserState message for each user
currently on the server, including the user that is currently connecting.

| Field | Type |
| ------------------ | -------- |
| `session` | `uint32` |
| `actor` | `uint32` |
| `name` | `string` |
| `user_id` | `uint32` |
| `channel_id` | `uint32` |
| `mute` | `bool` |
| `deaf` | `bool` |
| `suppress` | `bool` |
| `self_mute` | `bool` |
| `self_deaf` | `bool` |
| `texture` | `bytes` |
| `plugin_context` | `bytes` |
| `plugin_identity` | `string` |
| `comment` | `string` |
| `hash` | `string` |
| `comment_hash` | `bytes` |
| `texture_hash` | `bytes` |
| `priority_speaker` | `bool` |
| `recording` | `bool` |

## Server sync

The client has now received a copy of the parts of the server state it
needs to know about. To complete the synchronization the server transmits
a ServerSync message containing the session id of the clients session,
the maximum bandwidth allowed on this server, the servers welcome text
as well as the permissions the client has in the channel it ended up in.

For more information pease refer to the Mumble.proto file[^1].

## Ping

If the client wishes to maintain the connection to the server it is required
to ping the server. If the server does not receive a ping for 30 seconds it
will disconnect the client.

[^1]: <https://raw.github.com/mumble-voip/mumble/master/src/Mumble.proto>
Loading

0 comments on commit 9e30471

Please sign in to comment.