Skip to main content

ton_net_adnl/
lib.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: 2026 Nirapod Labs
3
4// A library that decodes bytes from a peer it does not trust must fail by returning, not
5// by unwinding: a panic in a decoder is a denial of service in whatever process embedded
6// it. The lints sit on the library because a test is the opposite case, where an unwrap
7// is the assertion. Arithmetic is deliberately not in the set: every count these formats
8// carry is bounded before it is used, and each subtraction sits within a few lines of the
9// guard that makes it safe, so denying it would bury the real bounds under checked_sub.
10#![deny(
11    clippy::unwrap_used,
12    clippy::expect_used,
13    clippy::panic,
14    clippy::unreachable,
15    clippy::todo,
16    clippy::indexing_slicing
17)]
18
19//! ADNL transport for ton-net: the encrypted link to a liteserver.
20//!
21//! ADNL is the transport TON nodes speak. This crate opens and runs a liteserver
22//! session over it, split along the sans-I/O seam of NET-ADR-002:
23//!
24//! - The protocol core is pure. [`client_handshake`] builds the 256-byte handshake
25//!   packet and derives the session ciphers, and [`SessionCiphers`] seals and opens the
26//!   stream frames. These are synchronous functions over bytes, tested against fixed
27//!   vectors, with no socket and no clock.
28//! - I/O lives behind the [`Transport`] seam. It moves ordered bytes and nothing more;
29//!   [`TcpTransport`] implements it over TCP. A browser transport is added later without
30//!   touching the core.
31//! - [`AdnlConnection`] is the async surface. It draws the per-session randomness from a
32//!   CSPRNG, completes the handshake over a transport, and runs a query to its answer.
33//!
34//! [`AdnlConnection`] speaks the ADNL message layer: it wraps a query with an id and
35//! matches the answer. The liteserver methods that build the query and decode the answer
36//! live in ton-net-lite.
37//!
38//! This is an internal crate of the ton-net client.
39#![forbid(unsafe_code)]
40#![warn(missing_docs)]
41#![deny(rustdoc::broken_intra_doc_links)]
42
43use sha2::{Digest, Sha256};
44
45pub mod connection;
46pub mod frame;
47pub mod handshake;
48pub mod transport;
49
50pub use connection::{AdnlConnection, AdnlError};
51pub use frame::{FrameError, SessionCiphers};
52pub use handshake::{client_handshake, Handshake, HandshakeError, HandshakeSecrets};
53pub use transport::{TcpTransport, Transport, TransportError};
54
55/// AES-256 in counter mode with a 128-bit big-endian counter: the ADNL stream cipher,
56/// used both to wrap the handshake parameters and to frame every session byte after.
57pub(crate) type Aes256Ctr = ctr::Ctr128BE<aes::Aes256>;
58
59/// SHA-256 over a sequence of byte slices, hashed in order as if concatenated.
60pub(crate) fn sha256(parts: &[&[u8]]) -> [u8; 32] {
61    let mut hasher = Sha256::new();
62    for part in parts {
63        hasher.update(part);
64    }
65    hasher.finalize().into()
66}
67
68// The README ships to crates.io and cannot be replaced once a version is published,
69// so its examples are compiled here rather than trusted. Doc-only: this does not
70// appear in the rendered documentation.
71#[cfg(doctest)]
72#[doc = include_str!("../README.md")]
73struct Readme;