ferogram_mtproto/
lib.rs

1/*
2 * Copyright (c) 2026 Ankit Chaubey <ankitchaubey.dev@gmail.com>
3 * https://github.com/ankit-chaubey
4 *
5 * Project: ferogram
6 * Website: https://ferogram.dev
7 *
8 * Licensed under the Apache License, Version 2.0 <LICENSE-APACHE or
9 * https://www.apache.org/licenses/LICENSE-2.0> or the MIT license
10 * <LICENSE-MIT or https://opensource.org/licenses/MIT>, at your option.
11 * This file may not be copied, modified, or distributed except according
12 * to those terms.
13 */
14
15#![cfg_attr(docsrs, feature(doc_cfg))]
16#![doc(html_root_url = "https://docs.rs/ferogram-mtproto/0.6.5")]
17//! MTProto 2.0 session management, message framing, DH key exchange, and transport abstractions.
18//!
19//! This crate is part of [ferogram](https://crates.io/crates/ferogram), an async Rust
20//! MTProto client built by [Ankit Chaubey](https://github.com/ankit-chaubey).
21//!
22//! - Channel: [t.me/Ferogram](https://t.me/Ferogram)
23//! - Chat: [t.me/FerogramChat](https://t.me/FerogramChat)
24//!
25//! Most users do not need this crate directly. Use the `ferogram` crate.
26//! This is for anyone building a lower-level MTProto stack on top of the
27//! crypto and framing primitives.
28//!
29//! # Modules
30//!
31//! - [`authentication`]: Sans-IO DH key exchange (steps 1-3 + finish).
32//!   Does no I/O itself; you drive it by passing the serialized requests
33//!   over your own transport and feeding back the responses.
34//! - [`encrypted`]: [`EncryptedSession`]: packs and unpacks MTProto 2.0
35//!   encrypted messages once you have a finished `AuthKey`.
36//! - [`session`]: [`Session`]: tracks plaintext sequence numbers and
37//!   message IDs for the pre-auth handshake phase.
38//! - [`transport`]: [`transport::Transport`] trait + [`transport::AbridgedTransport`] and
39//!   [`transport::ObfuscatedAbridged`] implementations over any `Read + Write` stream.
40//! - [`message`]: [`Message`] and [`MessageId`] framing types.
41//! - [`bind_temp_key`]: Helpers for binding a temporary auth key to a
42//!   permanent one (used by CDN and multi-DC flows).
43//!
44//! # DH handshake flow
45//!
46//! ```text
47//! let (req, s1) = authentication::step1()?;
48//! // serialize req, send over transport, receive resp (ResPQ)
49//! let (req, s2) = authentication::step2(s1, resp, dc_id)?;
50//! // serialize req, send, receive resp (ServerDhParams)
51//! let (req, s3) = authentication::step3(s2, resp)?;
52//! // serialize req, send, receive resp (SetClientDhParamsAnswer)
53//! let result = authentication::finish(s3, resp)?;
54//! // FinishResult::Done(d)  =>  d.auth_key is your 256-byte session key
55//! // FinishResult::Retry    =>  call retry_step3() + finish(), up to 5 times
56//! ```
57//!
58//! # Encrypted session
59//!
60//! ```rust,no_run
61//! use ferogram_mtproto::{EncryptedSession, authentication};
62//!
63//! # fn example(auth_key: [u8; 256], first_salt: i64, time_offset: i32) {
64//! let mut session = EncryptedSession::new(auth_key, first_salt, time_offset);
65//!
66//! // Pack an RPC call into an encrypted MTProto message
67//! // let wire = session.pack(&my_tl_function);
68//! // transport.send_message(&wire)?;
69//!
70//! // Unpack a received message
71//! // let decrypted = session.unpack(&mut raw_bytes)?;
72//! // decrypted.body contains the TL-serialized response
73//! # }
74//! ```
75//!
76//! # Transport
77//!
78//! Implement [`transport::Transport`] over any byte stream to get MTProto
79//! framing for free. Two built-in implementations are provided:
80//!
81//! - [`transport::AbridgedTransport`]: direct connection, no ISP protection.
82//! - [`transport::ObfuscatedAbridged`]: AES-CTR obfuscation that defeats
83//!   DPI-based blocking of plain Telegram traffic.
84
85#![deny(unsafe_code)]
86#![warn(missing_docs)]
87
88/// MTProto authentication key generation (DH handshake steps).
89pub mod authentication;
90/// Temporary/permanent auth key binding via `bindTempAuthKey`.
91pub mod bind_temp_key;
92/// Encrypted MTProto message construction and parsing.
93pub mod encrypted;
94/// MTProto message framing and container types.
95pub mod message;
96/// Session state: sequence numbers, salt, and server time.
97pub mod session;
98/// Transport-layer encoding (abridged, intermediate, padded).
99pub mod transport;
100
101pub use authentication::{
102    FinishResult, Finished, finish, retry_step3, step1, step2, step2_temp, step3,
103};
104pub use bind_temp_key::{
105    auth_key_id_from_key, encrypt_bind_inner, gen_msg_id, serialize_bind_temp_auth_key,
106};
107pub use encrypted::{
108    DecryptError, DecryptedMessage, EncryptedSession, SeenMsgIds, new_seen_msg_ids,
109};
110pub use message::{Message, MessageId};
111pub use session::Session;
ferogram_mtproto/lib.rs

ferogram_mtproto/
lib.rs
