Mumble.proto 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563
  1. // Copyright 2005-2018 The Mumble Developers. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license
  3. // that can be found in the LICENSE file at the root of the
  4. // Mumble source tree or at <https://www.mumble.info/LICENSE>.
  5. syntax = "proto2";
  6. package MumbleProto;
  7. option optimize_for = SPEED;
  8. message Version {
  9. // 2-byte Major, 1-byte Minor and 1-byte Patch version number.
  10. optional uint32 version = 1;
  11. // Client release name.
  12. optional string release = 2;
  13. // Client OS name.
  14. optional string os = 3;
  15. // Client OS version.
  16. optional string os_version = 4;
  17. }
  18. // Not used. Not even for tunneling UDP through TCP.
  19. message UDPTunnel {
  20. // Not used.
  21. required bytes packet = 1;
  22. }
  23. // Used by the client to send the authentication credentials to the server.
  24. message Authenticate {
  25. // UTF-8 encoded username.
  26. optional string username = 1;
  27. // Server or user password.
  28. optional string password = 2;
  29. // Additional access tokens for server ACL groups.
  30. repeated string tokens = 3;
  31. // A list of CELT bitstream version constants supported by the client.
  32. repeated int32 celt_versions = 4;
  33. optional bool opus = 5 [default = false];
  34. }
  35. // Sent by the client to notify the server that the client is still alive.
  36. // Server must reply to the packet with the same timestamp and its own
  37. // good/late/lost/resync numbers. None of the fields is strictly required.
  38. message Ping {
  39. // Client timestamp. Server should not attempt to decode.
  40. optional uint64 timestamp = 1;
  41. // The amount of good packets received.
  42. optional uint32 good = 2;
  43. // The amount of late packets received.
  44. optional uint32 late = 3;
  45. // The amount of packets never received.
  46. optional uint32 lost = 4;
  47. // The amount of nonce resyncs.
  48. optional uint32 resync = 5;
  49. // The total amount of UDP packets received.
  50. optional uint32 udp_packets = 6;
  51. // The total amount of TCP packets received.
  52. optional uint32 tcp_packets = 7;
  53. // UDP ping average.
  54. optional float udp_ping_avg = 8;
  55. // UDP ping variance.
  56. optional float udp_ping_var = 9;
  57. // TCP ping average.
  58. optional float tcp_ping_avg = 10;
  59. // TCP ping variance.
  60. optional float tcp_ping_var = 11;
  61. }
  62. // Sent by the server when it rejects the user connection.
  63. message Reject {
  64. enum RejectType {
  65. // The rejection reason is unknown (details should be available
  66. // in Reject.reason).
  67. None = 0;
  68. // The client attempted to connect with an incompatible version.
  69. WrongVersion = 1;
  70. // The user name supplied by the client was invalid.
  71. InvalidUsername = 2;
  72. // The client attempted to authenticate as a user with a password but it
  73. // was wrong.
  74. WrongUserPW = 3;
  75. // The client attempted to connect to a passworded server but the password
  76. // was wrong.
  77. WrongServerPW = 4;
  78. // Supplied username is already in use.
  79. UsernameInUse = 5;
  80. // Server is currently full and cannot accept more users.
  81. ServerFull = 6;
  82. // The user did not provide a certificate but one is required.
  83. NoCertificate = 7;
  84. AuthenticatorFail = 8;
  85. }
  86. // Rejection type.
  87. optional RejectType type = 1;
  88. // Human readable rejection reason.
  89. optional string reason = 2;
  90. }
  91. // ServerSync message is sent by the server when it has authenticated the user
  92. // and finished synchronizing the server state.
  93. message ServerSync {
  94. // The session of the current user.
  95. optional uint32 session = 1;
  96. // Maximum bandwidth that the user should use.
  97. optional uint32 max_bandwidth = 2;
  98. // Server welcome text.
  99. optional string welcome_text = 3;
  100. // Current user permissions in the root channel.
  101. optional uint64 permissions = 4;
  102. }
  103. // Sent by the client when it wants a channel removed. Sent by the server when
  104. // a channel has been removed and clients should be notified.
  105. message ChannelRemove {
  106. required uint32 channel_id = 1;
  107. }
  108. // Used to communicate channel properties between the client and the server.
  109. // Sent by the server during the login process or when channel properties are
  110. // updated. Client may use this message to update said channel properties.
  111. message ChannelState {
  112. // Unique ID for the channel within the server.
  113. optional uint32 channel_id = 1;
  114. // channel_id of the parent channel.
  115. optional uint32 parent = 2;
  116. // UTF-8 encoded channel name.
  117. optional string name = 3;
  118. // A collection of channel id values of the linked channels. Absent during
  119. // the first channel listing.
  120. repeated uint32 links = 4;
  121. // UTF-8 encoded channel description. Only if the description is less than
  122. // 128 bytes
  123. optional string description = 5;
  124. // A collection of channel_id values that should be added to links.
  125. repeated uint32 links_add = 6;
  126. // A collection of channel_id values that should be removed from links.
  127. repeated uint32 links_remove = 7;
  128. // True if the channel is temporary.
  129. optional bool temporary = 8 [default = false];
  130. // Position weight to tweak the channel position in the channel list.
  131. optional int32 position = 9 [default = 0];
  132. // SHA1 hash of the description if the description is 128 bytes or more.
  133. optional bytes description_hash = 10;
  134. // Maximum number of users allowed in the channel. If this value is zero,
  135. // the maximum number of users allowed in the channel is given by the
  136. // server's "usersperchannel" setting.
  137. optional uint32 max_users = 11;
  138. }
  139. // Used to communicate user leaving or being kicked. May be sent by the client
  140. // when it attempts to kick a user. Sent by the server when it informs the
  141. // clients that a user is not present anymore.
  142. message UserRemove {
  143. // The user who is being kicked, identified by their session, not present
  144. // when no one is being kicked.
  145. required uint32 session = 1;
  146. // The user who initiated the removal. Either the user who performs the kick
  147. // or the user who is currently leaving.
  148. optional uint32 actor = 2;
  149. // Reason for the kick, stored as the ban reason if the user is banned.
  150. optional string reason = 3;
  151. // True if the kick should result in a ban.
  152. optional bool ban = 4;
  153. }
  154. // Sent by the server when it communicates new and changed users to client.
  155. // First seen during login procedure. May be sent by the client when it wishes
  156. // to alter its state.
  157. message UserState {
  158. // Unique user session ID of the user whose state this is, may change on
  159. // reconnect.
  160. optional uint32 session = 1;
  161. // The session of the user who is updating this user.
  162. optional uint32 actor = 2;
  163. // User name, UTF-8 encoded.
  164. optional string name = 3;
  165. // Registered user ID if the user is registered.
  166. optional uint32 user_id = 4;
  167. // Channel on which the user is.
  168. optional uint32 channel_id = 5;
  169. // True if the user is muted by admin.
  170. optional bool mute = 6;
  171. // True if the user is deafened by admin.
  172. optional bool deaf = 7;
  173. // True if the user has been suppressed from talking by a reason other than
  174. // being muted.
  175. optional bool suppress = 8;
  176. // True if the user has muted self.
  177. optional bool self_mute = 9;
  178. // True if the user has deafened self.
  179. optional bool self_deaf = 10;
  180. // User image if it is less than 128 bytes.
  181. optional bytes texture = 11;
  182. // The positional audio plugin identifier.
  183. // Positional audio information is only sent to users who share
  184. // identical plugin contexts.
  185. //
  186. // This value is not trasmitted to clients.
  187. optional bytes plugin_context = 12;
  188. // The user's plugin-specific identity.
  189. // This value is not transmitted to clients.
  190. optional string plugin_identity = 13;
  191. // User comment if it is less than 128 bytes.
  192. optional string comment = 14;
  193. // The hash of the user certificate.
  194. optional string hash = 15;
  195. // SHA1 hash of the user comment if it 128 bytes or more.
  196. optional bytes comment_hash = 16;
  197. // SHA1 hash of the user picture if it 128 bytes or more.
  198. optional bytes texture_hash = 17;
  199. // True if the user is a priority speaker.
  200. optional bool priority_speaker = 18;
  201. // True if the user is currently recording.
  202. optional bool recording = 19;
  203. }
  204. // Relays information on the bans. The client may send the BanList message to
  205. // either modify the list of bans or query them from the server. The server
  206. // sends this list only after a client queries for it.
  207. message BanList {
  208. message BanEntry {
  209. // Banned IP address.
  210. required bytes address = 1;
  211. // The length of the subnet mask for the ban.
  212. required uint32 mask = 2;
  213. // User name for identification purposes (does not affect the ban).
  214. optional string name = 3;
  215. // The certificate hash of the banned user.
  216. optional string hash = 4;
  217. // Reason for the ban (does not affect the ban).
  218. optional string reason = 5;
  219. // Ban start time.
  220. optional string start = 6;
  221. // Ban duration in seconds.
  222. optional uint32 duration = 7;
  223. }
  224. // List of ban entries currently in place.
  225. repeated BanEntry bans = 1;
  226. // True if the server should return the list, false if it should replace old
  227. // ban list with the one provided.
  228. optional bool query = 2 [default = false];
  229. }
  230. // Used to send and broadcast text messages.
  231. message TextMessage {
  232. // The message sender, identified by its session.
  233. optional uint32 actor = 1;
  234. // Target users for the message, identified by their session.
  235. repeated uint32 session = 2;
  236. // The channels to which the message is sent, identified by their
  237. // channel_ids.
  238. repeated uint32 channel_id = 3;
  239. // The root channels when sending message recursively to several channels,
  240. // identified by their channel_ids.
  241. repeated uint32 tree_id = 4;
  242. // The UTF-8 encoded message. May be HTML if the server allows.
  243. required string message = 5;
  244. }
  245. message PermissionDenied {
  246. enum DenyType {
  247. // Operation denied for other reason, see reason field.
  248. Text = 0;
  249. // Permissions were denied.
  250. Permission = 1;
  251. // Cannot modify SuperUser.
  252. SuperUser = 2;
  253. // Invalid channel name.
  254. ChannelName = 3;
  255. // Text message too long.
  256. TextTooLong = 4;
  257. // The flux capacitor was spelled wrong.
  258. H9K = 5;
  259. // Operation not permitted in temporary channel.
  260. TemporaryChannel = 6;
  261. // Operation requires certificate.
  262. MissingCertificate = 7;
  263. // Invalid username.
  264. UserName = 8;
  265. // Channel is full.
  266. ChannelFull = 9;
  267. NestingLimit = 10;
  268. }
  269. // The denied permission when type is Permission.
  270. optional uint32 permission = 1;
  271. // channel_id for the channel where the permission was denied when type is
  272. // Permission.
  273. optional uint32 channel_id = 2;
  274. // The user who was denied permissions, identified by session.
  275. optional uint32 session = 3;
  276. // Textual reason for the denial.
  277. optional string reason = 4;
  278. // Type of the denial.
  279. optional DenyType type = 5;
  280. // The name that is invalid when type is UserName.
  281. optional string name = 6;
  282. }
  283. message ACL {
  284. message ChanGroup {
  285. // Name of the channel group, UTF-8 encoded.
  286. required string name = 1;
  287. // True if the group has been inherited from the parent (Read only).
  288. optional bool inherited = 2 [default = true];
  289. // True if the group members are inherited.
  290. optional bool inherit = 3 [default = true];
  291. // True if the group can be inherited by sub channels.
  292. optional bool inheritable = 4 [default = true];
  293. // Users explicitly included in this group, identified by user_id.
  294. repeated uint32 add = 5;
  295. // Users explicitly removed from this group in this channel if the group
  296. // has been inherited, identified by user_id.
  297. repeated uint32 remove = 6;
  298. // Users inherited, identified by user_id.
  299. repeated uint32 inherited_members = 7;
  300. }
  301. message ChanACL {
  302. // True if this ACL applies to the current channel.
  303. optional bool apply_here = 1 [default = true];
  304. // True if this ACL applies to the sub channels.
  305. optional bool apply_subs = 2 [default = true];
  306. // True if the ACL has been inherited from the parent.
  307. optional bool inherited = 3 [default = true];
  308. // ID of the user that is affected by this ACL.
  309. optional uint32 user_id = 4;
  310. // ID of the group that is affected by this ACL.
  311. optional string group = 5;
  312. // Bit flag field of the permissions granted by this ACL.
  313. optional uint32 grant = 6;
  314. // Bit flag field of the permissions denied by this ACL.
  315. optional uint32 deny = 7;
  316. }
  317. // Channel ID of the channel this message affects.
  318. required uint32 channel_id = 1;
  319. // True if the channel inherits its parent's ACLs.
  320. optional bool inherit_acls = 2 [default = true];
  321. // User group specifications.
  322. repeated ChanGroup groups = 3;
  323. // ACL specifications.
  324. repeated ChanACL acls = 4;
  325. // True if the message is a query for ACLs instead of setting them.
  326. optional bool query = 5 [default = false];
  327. }
  328. // Client may use this message to refresh its registered user information. The
  329. // client should fill the IDs or Names of the users it wants to refresh. The
  330. // server fills the missing parts and sends the message back.
  331. message QueryUsers {
  332. // user_ids.
  333. repeated uint32 ids = 1;
  334. // User names in the same order as ids.
  335. repeated string names = 2;
  336. }
  337. // Used to initialize and resync the UDP encryption. Either side may request a
  338. // resync by sending the message without any values filled. The resync is
  339. // performed by sending the message with only the client or server nonce
  340. // filled.
  341. message CryptSetup {
  342. // Encryption key.
  343. optional bytes key = 1;
  344. // Client nonce.
  345. optional bytes client_nonce = 2;
  346. // Server nonce.
  347. optional bytes server_nonce = 3;
  348. }
  349. message ContextActionModify {
  350. enum Context {
  351. // Action is applicable to the server.
  352. Server = 0x01;
  353. // Action can target a Channel.
  354. Channel = 0x02;
  355. // Action can target a User.
  356. User = 0x04;
  357. }
  358. enum Operation {
  359. Add = 0;
  360. Remove = 1;
  361. }
  362. // The action name.
  363. required string action = 1;
  364. // The display name of the action.
  365. optional string text = 2;
  366. // Context bit flags defining where the action should be displayed.
  367. optional uint32 context = 3;
  368. optional Operation operation = 4;
  369. }
  370. // Sent by the client when it wants to initiate a Context action.
  371. message ContextAction {
  372. // The target User for the action, identified by session.
  373. optional uint32 session = 1;
  374. // The target Channel for the action, identified by channel_id.
  375. optional uint32 channel_id = 2;
  376. // The action that should be executed.
  377. required string action = 3;
  378. }
  379. // Lists the registered users.
  380. message UserList {
  381. message User {
  382. // Registered user ID.
  383. required uint32 user_id = 1;
  384. // Registered user name.
  385. optional string name = 2;
  386. optional string last_seen = 3;
  387. optional uint32 last_channel = 4;
  388. }
  389. // A list of registered users.
  390. repeated User users = 1;
  391. }
  392. // Sent by the client when it wants to register or clear whisper targets.
  393. //
  394. // Note: The first available target ID is 1 as 0 is reserved for normal
  395. // talking. Maximum target ID is 30.
  396. message VoiceTarget {
  397. message Target {
  398. // Users that are included as targets.
  399. repeated uint32 session = 1;
  400. // Channel that is included as a target.
  401. optional uint32 channel_id = 2;
  402. // ACL group that is included as a target.
  403. optional string group = 3;
  404. // True if the voice should follow links from the specified channel.
  405. optional bool links = 4 [default = false];
  406. // True if the voice should also be sent to children of the specific
  407. // channel.
  408. optional bool children = 5 [default = false];
  409. }
  410. // Voice target ID.
  411. optional uint32 id = 1;
  412. // The receivers that this voice target includes.
  413. repeated Target targets = 2;
  414. }
  415. // Sent by the client when it wants permissions for a certain channel. Sent by
  416. // the server when it replies to the query or wants the user to resync all
  417. // channel permissions.
  418. message PermissionQuery {
  419. // channel_id of the channel for which the permissions are queried.
  420. optional uint32 channel_id = 1;
  421. // Channel permissions.
  422. optional uint32 permissions = 2;
  423. // True if the client should drop its current permission information for all
  424. // channels.
  425. optional bool flush = 3 [default = false];
  426. }
  427. // Sent by the server to notify the users of the version of the CELT codec they
  428. // should use. This may change during the connection when new users join.
  429. message CodecVersion {
  430. // The version of the CELT Alpha codec.
  431. required int32 alpha = 1;
  432. // The version of the CELT Beta codec.
  433. required int32 beta = 2;
  434. // True if the user should prefer Alpha over Beta.
  435. required bool prefer_alpha = 3 [default = true];
  436. optional bool opus = 4 [default = false];
  437. }
  438. // Used to communicate user stats between the server and clients.
  439. message UserStats {
  440. message Stats {
  441. // The amount of good packets received.
  442. optional uint32 good = 1;
  443. // The amount of late packets received.
  444. optional uint32 late = 2;
  445. // The amount of packets never received.
  446. optional uint32 lost = 3;
  447. // The amount of nonce resyncs.
  448. optional uint32 resync = 4;
  449. }
  450. // User whose stats these are.
  451. optional uint32 session = 1;
  452. // True if the message contains only mutable stats (packets, ping).
  453. optional bool stats_only = 2 [default = false];
  454. // Full user certificate chain of the user certificate in DER format.
  455. repeated bytes certificates = 3;
  456. // Packet statistics for packets received from the client.
  457. optional Stats from_client = 4;
  458. // Packet statistics for packets sent by the server.
  459. optional Stats from_server = 5;
  460. // Amount of UDP packets sent.
  461. optional uint32 udp_packets = 6;
  462. // Amount of TCP packets sent.
  463. optional uint32 tcp_packets = 7;
  464. // UDP ping average.
  465. optional float udp_ping_avg = 8;
  466. // UDP ping variance.
  467. optional float udp_ping_var = 9;
  468. // TCP ping average.
  469. optional float tcp_ping_avg = 10;
  470. // TCP ping variance.
  471. optional float tcp_ping_var = 11;
  472. // Client version.
  473. optional Version version = 12;
  474. // A list of CELT bitstream version constants supported by the client of this
  475. // user.
  476. repeated int32 celt_versions = 13;
  477. // Client IP address.
  478. optional bytes address = 14;
  479. // Bandwith used by this client.
  480. optional uint32 bandwidth = 15;
  481. // Connection duration.
  482. optional uint32 onlinesecs = 16;
  483. // Duration since last activity.
  484. optional uint32 idlesecs = 17;
  485. // True if the user has a strong certificate.
  486. optional bool strong_certificate = 18 [default = false];
  487. optional bool opus = 19 [default = false];
  488. }
  489. // Used by the client to request binary data from the server. By default large
  490. // comments or textures are not sent within standard messages but instead the
  491. // hash is. If the client does not recognize the hash it may request the
  492. // resource when it needs it. The client does so by sending a RequestBlob
  493. // message with the correct fields filled with the user sessions or channel_ids
  494. // it wants to receive. The server replies to this by sending a new
  495. // UserState/ChannelState message with the resources filled even if they would
  496. // normally be transmitted as hashes.
  497. message RequestBlob {
  498. // sessions of the requested UserState textures.
  499. repeated uint32 session_texture = 1;
  500. // sessions of the requested UserState comments.
  501. repeated uint32 session_comment = 2;
  502. // channel_ids of the requested ChannelState descriptions.
  503. repeated uint32 channel_description = 3;
  504. }
  505. // Sent by the server when it informs the clients on server configuration
  506. // details.
  507. message ServerConfig {
  508. // The maximum bandwidth the clients should use.
  509. optional uint32 max_bandwidth = 1;
  510. // Server welcome text.
  511. optional string welcome_text = 2;
  512. // True if the server allows HTML.
  513. optional bool allow_html = 3;
  514. // Maximum text message length.
  515. optional uint32 message_length = 4;
  516. // Maximum image message length.
  517. optional uint32 image_message_length = 5;
  518. // The maximum number of users allowed on the server.
  519. optional uint32 max_users = 6;
  520. }
  521. // Sent by the server to inform the clients of suggested client configuration
  522. // specified by the server administrator.
  523. message SuggestConfig {
  524. // Suggested client version.
  525. optional uint32 version = 1;
  526. // True if the administrator suggests positional audio to be used on this
  527. // server.
  528. optional bool positional = 2;
  529. // True if the administrator suggests push to talk to be used on this server.
  530. optional bool push_to_talk = 3;
  531. }