diff --git a/telethon/crypto/__init__.py b/telethon/crypto/__init__.py index d151a96c..aa470adf 100644 --- a/telethon/crypto/__init__.py +++ b/telethon/crypto/__init__.py @@ -1,3 +1,8 @@ +""" +This module contains several utilities regarding cryptographic purposes, +such as the AES IGE mode used by Telegram, the authorization key bound with +their data centers, and so on. +""" from .aes import AES from .aes_ctr import AESModeCTR from .auth_key import AuthKey diff --git a/telethon/crypto/aes.py b/telethon/crypto/aes.py index c09add56..191cde15 100644 --- a/telethon/crypto/aes.py +++ b/telethon/crypto/aes.py @@ -1,3 +1,6 @@ +""" +AES IGE implementation in Python. This module may use libssl if available. +""" import os import pyaes from . import libssl @@ -9,10 +12,15 @@ if libssl.AES is not None: else: # Fallback to a pure Python implementation class AES: + """ + Class that servers as an interface to encrypt and decrypt + text through the AES IGE mode. + """ @staticmethod def decrypt_ige(cipher_text, key, iv): - """Decrypts the given text in 16-bytes blocks by using the - given key and 32-bytes initialization vector + """ + Decrypts the given text in 16-bytes blocks by using the + given key and 32-bytes initialization vector. """ iv1 = iv[:len(iv) // 2] iv2 = iv[len(iv) // 2:] @@ -42,8 +50,9 @@ else: @staticmethod def encrypt_ige(plain_text, key, iv): - """Encrypts the given text in 16-bytes blocks by using the - given key and 32-bytes initialization vector + """ + Encrypts the given text in 16-bytes blocks by using the + given key and 32-bytes initialization vector. """ # Add random padding iff it's not evenly divisible by 16 already diff --git a/telethon/crypto/aes_ctr.py b/telethon/crypto/aes_ctr.py index 7bd7b79a..34422904 100644 --- a/telethon/crypto/aes_ctr.py +++ b/telethon/crypto/aes_ctr.py @@ -1,3 +1,6 @@ +""" +This module holds the AESModeCTR wrapper class. +""" import pyaes @@ -6,6 +9,12 @@ class AESModeCTR: # TODO Maybe make a pull request to pyaes to support iv on CTR def __init__(self, key, iv): + """ + Initializes the AES CTR mode with the given key/iv pair. + + :param key: the key to be used as bytes. + :param iv: the bytes initialization vector. Must have a length of 16. + """ # TODO Use libssl if available assert isinstance(key, bytes) self._aes = pyaes.AESModeOfOperationCTR(key) @@ -15,7 +24,19 @@ class AESModeCTR: self._aes._counter._counter = list(iv) def encrypt(self, data): + """ + Encrypts the given plain text through AES CTR. + + :param data: the plain text to be encrypted. + :return: the encrypted cipher text. + """ return self._aes.encrypt(data) def decrypt(self, data): + """ + Decrypts the given cipher text through AES CTR + + :param data: the cipher text to be decrypted. + :return: the decrypted plain text. + """ return self._aes.decrypt(data) diff --git a/telethon/crypto/auth_key.py b/telethon/crypto/auth_key.py index 17a7f8ca..679e62ff 100644 --- a/telethon/crypto/auth_key.py +++ b/telethon/crypto/auth_key.py @@ -1,3 +1,6 @@ +""" +This module holds the AuthKey class. +""" import struct from hashlib import sha1 @@ -6,7 +9,16 @@ from ..extensions import BinaryReader class AuthKey: + """ + Represents an authorization key, used to encrypt and decrypt + messages sent to Telegram's data centers. + """ def __init__(self, data): + """ + Initializes a new authorization key. + + :param data: the data in bytes that represent this auth key. + """ self.key = data with BinaryReader(sha1(self.key).digest()) as reader: @@ -15,8 +27,12 @@ class AuthKey: self.key_id = reader.read_long(signed=False) def calc_new_nonce_hash(self, new_nonce, number): - """Calculates the new nonce hash based on - the current class fields' values + """ + Calculates the new nonce hash based on the current attributes. + + :param new_nonce: the new nonce to be hashed. + :param number: number to prepend before the hash. + :return: the hash for the given new nonce. """ new_nonce = new_nonce.to_bytes(32, 'little', signed=True) data = new_nonce + struct.pack('