🔐 Fast Telegram Crypto Library for Python
Switch branches/tags
Clone or download
Latest commit 95ff73c Sep 19, 2018
Permalink
Failed to load latest commit information.
tgcrypto Update to v1.1.1 Sep 20, 2018
.gitignore Initial commit Jan 27, 2018
COPYING Initial commit Jan 27, 2018
COPYING.lesser Initial commit Jan 27, 2018
MANIFEST.in Initial commit Jan 27, 2018
NOTICE Initial commit Jan 27, 2018
README.rst Update to v1.1.1 Sep 20, 2018
setup.py Update to v1.1.1 Sep 20, 2018

README.rst

TgCrypto Logo

Fast Telegram Crypto Library for Python
Download Documentation Community

TgCrypto TgCrypto

Table of Contents

About

TgCrypto is a high-performance, easy-to-install Telegram Crypto Library written in C as a Python extension. TgCrypto is intended for Pyrogram [1] and implements the crypto algorithms Telegram requires, namely AES-IGE 256 bit (used in MTProto v2.0) and AES-CTR 256 bit (used for CDN encrypted files).

Installation

$ pip3 install --upgrade tgcrypto

Note: Being a C extension for Python, TgCrypto is an optional but highly recommended Pyrogram dependency; if TgCrypto is not detected in your system, Pyrogram will automatically fall back to the much slower PyAES and will show you a warning.

The reason about being an optional package is that TgCrypto requires some extra system tools in order to be compiled. The errors you receive when trying to install TgCrypto are system dependent, but also descriptive enough to understand what you should do next:

  • Windows: Install Visual C++ 2015 Build Tools.
  • macOS: A pop-up will automatically ask you to install the command line developer tools.
  • Linux: Install a proper C compiler (gcc, clang) and the Python header files (python3-dev).
  • Termux (Android): Install clang and python-dev packages.

API

TgCrypto API consists of these four methods:

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:

Usage

IGE Mode:

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

import os
import tgcrypto

data = os.urandom(10 * 1024 * 1024 + 7)  # 10 MB of random data + 7 bytes to show padding
key = os.urandom(32)  # Random Key
iv = os.urandom(32)  # Random IV

# Pad with zeroes: -7 % 16 = 9
data += bytes(-len(data) % 16)

ige_encrypted = tgcrypto.ige256_encrypt(data, key, iv)
ige_decrypted = tgcrypto.ige256_decrypt(ige_encrypted, key, iv)

print(data == ige_decrypted)  # True

CTR Mode (single chunk):

import os
import tgcrypto

data = os.urandom(10 * 1024 * 1024)  # 10 MB of random data

key = os.urandom(32)  # Random Key

enc_iv = bytearray(os.urandom(16))  # Random IV
dec_iv = enc_iv.copy()  # Keep a copy for decryption

ctr_encrypted = tgcrypto.ctr256_encrypt(data, key, enc_iv, bytes(1))
ctr_decrypted = tgcrypto.ctr256_decrypt(ctr_encrypted, key, dec_iv, bytes(1))

print(data == ctr_decrypted)  # True

CTR Mode (stream):

import os
import tgcrypto
from io import BytesIO

data = BytesIO(os.urandom(10 * 1024 * 1024))  # 10 MB of random data

key = os.urandom(32)  # Random Key

enc_iv = bytearray(os.urandom(16))  # Random IV
dec_iv = enc_iv.copy()  # Keep a copy for decryption

enc_state = bytes(1)  # Encryption state, starts from 0
dec_state = bytes(1)  # Decryption state, starts from 0

encrypted_data = BytesIO()  # Encrypted data buffer
decrypted_data = BytesIO()  # Decrypted data buffer

while True:
    chunk = data.read(1024)

    if not chunk:
        break

    # Write 1K encrypted bytes into the encrypted data buffer
    encrypted_data.write(tgcrypto.ctr256_encrypt(chunk, key, enc_iv, enc_state))

# Reset position. We need to read it now
encrypted_data.seek(0)

while True:
    chunk = encrypted_data.read(1024)

    if not chunk:
        break

    # Write 1K decrypted bytes into the decrypted data buffer
    decrypted_data.write(tgcrypto.ctr256_decrypt(chunk, key, dec_iv, dec_state))

print(data.getvalue() == decrypted_data.getvalue())  # True

Contribution

You are very welcome to contribute by either submitting pull requests or reporting issues/bugs as well as suggesting best practices, ideas, enhancements on both code and documentation. Any help is appreciated!

Feedback

Means for getting in touch:

License


[1]Although TgCrypto is intended for Pyrogram, it is shipped as a standalone package and can thus be used for any other Python project too.