Metadata-Version: 2.4
Name: TgCryptoRust
Version: 1.2.0
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Internet
Classifier: Topic :: Communications
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Python Modules
License-File: COPYING
License-File: COPYING.lesser
Summary: Rust-powered drop-in replacement for TgCrypto
Keywords: kurigram,telegram,crypto,cryptography,encryption,mtproto,aes,rust
License-Expression: LGPL-3.0-or-later
Requires-Python: >=3.9, <3.15
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Homepage, https://github.com/joyccn/TgCryptoRust
Project-URL: Source, https://github.com/joyccn/TgCryptoRust

# TgCryptoRust

> [!NOTE]
> This project is provided for educational and experimental purposes. The
> implementation follows public AES specifications and is tested against known
> vectors, but it has not received a formal third-party security audit. Do not
> treat it as a certified cryptographic module.

Rust-powered, AES-NI accelerated cryptography for Telegram clients.

[![CI](https://github.com/joyccn/TgCryptoRust/actions/workflows/ci.yml/badge.svg)](https://github.com/joyccn/TgCryptoRust/actions/workflows/ci.yml)
![License](https://img.shields.io/badge/license-LGPLv3+-blue)
![Python](https://img.shields.io/badge/python-3.9--3.14-brightgreen)
![Rust](https://img.shields.io/badge/rust-1.83%2B-orange)

**TgCryptoRust** is a drop-in replacement for [TgCrypto](https://github.com/pyrogram/tgcrypto),
implemented in Rust and packaged for Python through PyO3 and Maturin.
It implements the cryptographic algorithms Telegram requires, namely:

- **`AES-256-IGE`** — used in [MTProto v2.0](https://core.telegram.org/mtproto).
- **`AES-256-CTR`** — used for [CDN encrypted files](https://core.telegram.org/cdn).
- **`AES-256-CBC`** — used for [encrypted passport credentials](https://core.telegram.org/passport).

## Requirements

- Python 3.9 through 3.14
- Rust 1.83+ (only when building from source)

Prebuilt wheels are available for common desktop and server platforms.
Rust is only required when a wheel is not available for your platform.

## Installation

```bash
pip install TgCryptoRust
```

Or with `uv`:

```bash
uv add TgCryptoRust
uv sync
```

## API

```python
def ige256_encrypt(data: bytes, key: bytes, iv: bytes) -> bytes: ...
def ige256_decrypt(data: bytes, key: bytes, iv: bytes) -> bytes: ...

def ctr256_encrypt(data: bytes, key: bytes, iv: bytes, state: bytes) -> bytes: ...
def ctr256_decrypt(data: bytes, key: bytes, iv: bytes, state: bytes) -> bytes: ...

def cbc256_encrypt(data: bytes, key: bytes, iv: bytes) -> bytes: ...
def cbc256_decrypt(data: bytes, key: bytes, iv: bytes) -> bytes: ...
```

## Usage

### IGE Mode

**Note**: Data must be padded to a multiple of the block size (16 bytes).

```python
import os
import tgcrypto

data = os.urandom(1024)
key = os.urandom(32)
iv = os.urandom(32)

encrypted = tgcrypto.ige256_encrypt(data, key, iv)
decrypted = tgcrypto.ige256_decrypt(encrypted, key, iv)

assert decrypted == data
```

### CTR Mode

CTR accepts arbitrary-length data. The `state` argument is a one-byte offset
inside the current keystream block, kept for TgCrypto compatibility.

```python
import os
import tgcryptors

data = os.urandom(1000)
key = os.urandom(32)
iv = os.urandom(16)
state = b"\x00"

encrypted = tgcryptors.ctr256_encrypt(data, key, iv, state)
decrypted = tgcryptors.ctr256_decrypt(encrypted, key, iv, state)

assert decrypted == data
```

### CBC Mode

**Note**: Data must be padded to a multiple of the block size (16 bytes).

```python
import os
import tgcrypto

data = os.urandom(1024)
key = os.urandom(32)
iv = os.urandom(16)

encrypted = tgcrypto.cbc256_encrypt(data, key, iv)
decrypted = tgcrypto.cbc256_decrypt(encrypted, key, iv)

assert decrypted == data
```

### Streaming API

Use the streaming classes when processing one logical stream in chunks.
The key schedule is expanded once and reused.

```python
import os
import tgcryptors

key = os.urandom(32)
iv = os.urandom(16)
data = os.urandom(1024)

stream = tgcryptors.Ctr256(key, iv)
encrypted = stream.update(data[:300]) + stream.update(data[300:])
```

IGE streaming is also available for block-aligned chunks:

```python
import os
import tgcrypto

key = os.urandom(32)
iv = os.urandom(32)
data = os.urandom(1024)

stream = tgcrypto.Ige256(key, iv)
encrypted = stream.encrypt(data[:512]) + stream.encrypt(data[512:])
```

### Runtime Metadata

```python
import tgcryptors

print(tgcryptors.__version__)
print(tgcryptors.runtime_info())
```

## Imports

Existing TgCrypto users can keep importing `tgcrypto`:

```python
import tgcrypto
```

New code can import the branded module directly:

```python
import tgcryptors
```

Both modules expose the same API.

## Compatibility

TgCryptoRust is a full drop-in replacement. All function names, argument orders,
return types, and validation behavior match the original TgCrypto:

| Function | Arguments |
|----------|-----------|
| `ige256_encrypt` | `(data, key, iv)` |
| `ige256_decrypt` | `(data, key, iv)` |
| `ctr256_encrypt` | `(data, key, iv, state)` |
| `ctr256_decrypt` | `(data, key, iv, state)` |
| `cbc256_encrypt` | `(data, key, iv)` |
| `cbc256_decrypt` | `(data, key, iv)` |

## Architecture

- **`tgcryptors-core`** — Rust AES primitive and Telegram block modes (IGE, CTR, CBC).
- **`tgcryptors-python`** — PyO3 extension module exposing the native API.
- **`python/tgcrypto`** — Compatibility shim re-exporting `tgcryptors` for existing imports.
- **`tests/`** — Python unit tests covering the public API.

On x86 and x86_64, AES-NI is detected at runtime when the crate is built with
the default `aesni` feature. Other targets use a software fallback (T-table based,
not guaranteed constant-time on every CPU).

## Migrating From TgrCrypto

`TgrCrypto` is deprecated in favor of `TgCryptoRust`.

```bash
pip uninstall TgrCrypto
pip install TgCryptoRust
```

Existing code that imports `tgcrypto` can remain unchanged.

## Development

```bash
# Set up environment
uv sync --python 3.14

# Build and install the native module
uv run maturin develop --release

# Run Python tests
.venv/bin/python -m unittest discover -s tests -v
```

Run the Rust checks:

```bash
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --release
```

Build a wheel:

```bash
uv build --wheel
```

## License

[LGPLv3+](COPYING.lesser) — GNU Lesser General Public License v3 or later.

© 2025-Present Joy. See [COPYING](COPYING) and [COPYING.lesser](COPYING.lesser).

