ferogram_mtproto/
lib.rs

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

ferogram_mtproto/
lib.rs
