ferogram_mtproto/
lib.rs

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

ferogram_mtproto/
lib.rs
