📡 layer-mtproto

MTProto 2.0 session management, DH key exchange, and message framing for Rust.

A complete, from-scratch implementation of Telegram's MTProto 2.0 session layer.

📦 Installation

[dependencies]
layer-mtproto  = "0.4.5"
layer-tl-types = { version = "0.4.5", features = ["tl-mtproto"] }

✨ What It Does

layer-mtproto implements the full MTProto 2.0 session layer — the encrypted tunnel through which all Telegram API calls travel. This is the core protocol machinery that sits between your application code and the TCP socket.

It handles:

🤝 3-step DH key exchange — deriving a shared auth key from scratch
🔐 Encrypted sessions — packing/unpacking MTProto 2.0 messages with AES-IGE
📦 Message framing — salt, session_id, message_id, sequence numbers
🗜️ Containers & compression — msg_container, gzip_packed responses
🧂 Salt management — server salt tracking and auto-correction
🔄 Session state — time offset, sequence number, salt rotation
🔁 Error recovery — bad_msg_notification, bad_server_salt, msg_resend_req
✅ Acknowledgements — MsgsAck with a pending-ack queue

🏗️ Architecture

Application (layer-client)
       │
       ▼
  EncryptedSession         ← encrypt/decrypt, pack/unpack
       │
       ▼
  Authentication           ← 3-step DH handshake (step1 → step2 → step3 → finish)
       │
       ▼
  layer-crypto             ← AES-IGE, RSA, SHA, Diffie-Hellman
       │
       ▼
  TCP Socket

📚 Core Types

`EncryptedSession`

Manages the live MTProto session after a key has been established.

use layer_mtproto::EncryptedSession;

// Create from a completed DH handshake
let session = EncryptedSession::new(auth_key, first_salt, time_offset);

// Pack a RemoteCall into encrypted wire bytes
let wire_bytes = session.pack(&my_request)?;

// Pack any Serializable directly (bypasses RemoteCall bound)
let wire_bytes = session.pack_serializable(&raw_obj)?;

// Unpack an encrypted response from the server
let msg = session.unpack(&mut raw_bytes)?;
println!("msg_id={}, body_len={}", msg.msg_id, msg.body.len());

`authentication` — 3-Step DH Key Exchange

The full MTProto DH handshake as specified by Telegram:

use layer_mtproto::authentication as auth;

// Step 1 — req_pq_multi: get the server's PQ
let (req1, state1) = auth::step1()?;
// ... send req1 over the wire, receive res_pq ...

// Step 2 — req_DH_params: send our DH parameters
let (req2, state2) = auth::step2(state1, res_pq)?;
// ... send req2, receive server_DH_params ...

// Step 3 — set_client_DH_params: send our client DH
let (req3, state3) = auth::step3(state2, dh_params)?;
// ... send req3, receive dh_answer ...

// Finish — derive the auth key from the completed handshake
let done = auth::finish(state3, dh_answer)?;

// done.auth_key    → [u8; 256]   — the shared secret
// done.first_salt  → i64         — first server salt to use
// done.time_offset → i32         — clock skew relative to server

`Message`

A decoded MTProto message as returned by session.unpack():

pub struct Message {
    pub msg_id:  i64,
    pub seq_no:  i32,
    pub salt:    i64,
    pub body:    Vec<u8>,   // raw TL bytes of the inner object
}

The body bytes are deserialized by layer-client using layer-tl-types's Deserializable trait.

`Session` (plain / unencrypted)

Used only for sending the initial DH handshake messages before an auth key exists:

use layer_mtproto::Session;

let mut plain = Session::new();
// Pack a plaintext MTProto message
let framed = plain.pack_plain(&my_handshake_request)?;

🔍 What's Inside

Encryption Details

AES-IGE encryption/decryption via layer-crypto
msg_key = SHA-256 of (auth_key[88..120] || plaintext) for client→server
msg_key = SHA-256 of (auth_key[96..128] || plaintext) for server→client
The 256-byte auth key is split into sub-keys for encryption, MAC, and padding

Message Framing

Every outgoing MTProto message has this structure:

server_salt     (8 bytes) — current server salt
session_id      (8 bytes) — random, stable for this session's lifetime
message_id      (8 bytes) — Unix time * 2^32, monotonically increasing
seq_no          (4 bytes) — content-related message counter
message_length  (4 bytes) — length of payload in bytes
payload         (N bytes) — serialized TL object
padding         (M bytes) — 12–1024 random bytes so total % 16 == 0

Wrapped in a 32-byte msg_key prefix after encryption.

Containers & Compression

msg_container (TL ID 0x73f1f8dc) — wraps multiple logical messages in one TCP frame; both packing and unpacking are supported
gzip_packed (TL ID 0x3072cfa1) — response bodies are decompressed automatically; outgoing large requests are optionally compressed

Salt & Time Management

bad_server_salt — session records the corrected salt and automatically resets
future_salts prefetch — salts are requested in advance; session rotates before expiry
time_offset correction — all outgoing msg_id values are adjusted for clock skew

Error Recovery

bad_msg_notification — messages with wrong msg_id, seq_no, or session_id are resent with corrected framing
seq_no auto-correction for error codes 32 (seq_no too low) and 33 (seq_no too high)
msg_resend_req — fulfils resend requests by replaying from a sent-body cache

Acknowledgements

Received content-related messages accumulate in a pending_ack list
The flush_acks() call bundles them into a single MsgsAck message
layer-client flushes pending ACKs on a timer and before each outgoing call

🔗 Part of the layer stack

layer-client
└── layer-mtproto     ← you are here
    ├── layer-tl-types  (tl-mtproto feature)
    └── layer-crypto

📄 License

Licensed under either of, at your option:

MIT License — see LICENSE-MIT
Apache License, Version 2.0 — see LICENSE-APACHE

👤 Author

Ankit Chaubey
github.com/ankit-chaubey · ankitchaubey.in · ankitchaubey.dev@gmail.com

📦 github.com/ankit-chaubey/layer

layer-mtproto 0.4.5