grammpars 0.1.0

Offline conversion between Telegram Desktop tdata, Telethon, and grammers sessions
Documentation
use crate::crypto::CryptoUtils;
use crate::error::{OpenteleError, Result};
use crate::td::auth::{AuthKey, AuthKeyType};
use md5::{Digest, Md5};
use rand::RngCore;
use sha1::Sha1;
use std::fs::{File, OpenOptions};
use std::io::{Read, Write};
use std::path::{Path, PathBuf};

/// AES block size used by IGE mode.
pub const AES_BLOCK_SIZE: usize = 16;
/// Mask used to test AES block alignment.
pub const AES_BLOCK_MASK: usize = 0x0f;
/// Telegram Desktop storage-file magic.
pub const TDF_MAGIC: &[u8; 4] = b"TDF$";
/// Defensive maximum size accepted for one TDF file.
pub const MAX_TDF_FILE_SIZE: u64 = 64 * 1024 * 1024;

/// Low-level Telegram Desktop storage operations.
pub struct Storage;

impl Storage {
    /// Authenticates and decrypts one local-storage value.
    ///
    /// # Errors
    ///
    /// Returns an error for invalid block alignment, malformed lengths, an
    /// invalid authorization key, a checksum mismatch, or failed decryption.
    pub fn decrypt_local(encrypted: &[u8], auth_key: &AuthKey) -> Result<Vec<u8>> {
        let encrypted_size = encrypted.len();
        if encrypted_size <= AES_BLOCK_SIZE || (encrypted_size & AES_BLOCK_MASK) != 0 {
            return Err(OpenteleError::InvalidTData(format!(
                "bad encrypted part size: {encrypted_size}"
            )));
        }

        let encrypted_key = &encrypted[..AES_BLOCK_SIZE];
        let encrypted_data = &encrypted[AES_BLOCK_SIZE..];
        let (aes_key, aes_iv) =
            CryptoUtils::prepare_aes_oldmtp(encrypted_key, auth_key.as_bytes(), false)?;
        let mut decrypted = CryptoUtils::aes_ige_decrypt(encrypted_data, &aes_key, &aes_iv)?;

        let mut hasher = Sha1::new();
        hasher.update(&decrypted);
        let check_hash = hasher.finalize();
        if &check_hash[..AES_BLOCK_SIZE] != encrypted_key {
            return Err(OpenteleError::CryptoError(
                "data could not be decrypted (incorrect passcode or corrupt input)".into(),
            ));
        }

        let full_len = decrypted.len();
        let data_len = u32::from_le_bytes(
            decrypted[..4]
                .try_into()
                .expect("validated encrypted blocks always contain four bytes"),
        ) as usize;
        if data_len > full_len
            || data_len <= full_len.saturating_sub(AES_BLOCK_SIZE)
            || data_len < 4
        {
            return Err(OpenteleError::InvalidTData(format!(
                "bad decrypted part size: {data_len}, full length: {full_len}"
            )));
        }

        decrypted.truncate(data_len);
        Ok(decrypted[4..].to_vec())
    }

    /// Rounds a byte count up to the next AES block boundary.
    ///
    /// # Errors
    ///
    /// Returns an error when rounding would overflow [`usize`].
    pub fn pad_to_block(size: usize) -> Result<usize> {
        let remainder = size & AES_BLOCK_MASK;
        if remainder == 0 {
            Ok(size)
        } else {
            size.checked_add(AES_BLOCK_SIZE - remainder).ok_or_else(|| {
                OpenteleError::InvalidArgument("encrypted value is too large".into())
            })
        }
    }

    /// Pads, authenticates, and encrypts one local-storage value.
    ///
    /// # Errors
    ///
    /// Returns an error when the input is too large, block size calculation
    /// overflows, the key is invalid, or AES encryption fails.
    pub fn prepare_encrypted(data: &[u8], key: &AuthKey) -> Result<Vec<u8>> {
        let unpadded_size = data
            .len()
            .checked_add(4)
            .ok_or_else(|| OpenteleError::InvalidArgument("encrypted value is too large".into()))?;
        let data_size = u32::try_from(unpadded_size).map_err(|_| {
            OpenteleError::InvalidArgument("encrypted value is larger than u32::MAX".into())
        })?;
        let full_size = Self::pad_to_block(unpadded_size)?;

        let mut to_encrypt = vec![0u8; full_size];
        to_encrypt[..4].copy_from_slice(&data_size.to_le_bytes());
        to_encrypt[4..unpadded_size].copy_from_slice(data);
        rand::thread_rng().fill_bytes(&mut to_encrypt[unpadded_size..]);

        let mut hasher = Sha1::new();
        hasher.update(&to_encrypt);
        let hash_data = hasher.finalize();

        let mut encrypted = vec![0u8; AES_BLOCK_SIZE + full_size];
        encrypted[..AES_BLOCK_SIZE].copy_from_slice(&hash_data[..AES_BLOCK_SIZE]);
        let (aes_key, aes_iv) =
            CryptoUtils::prepare_aes_oldmtp(&encrypted[..AES_BLOCK_SIZE], key.as_bytes(), false)?;
        let encrypted_data = CryptoUtils::aes_ige_encrypt(&to_encrypt, &aes_key, &aes_iv)?;
        encrypted[AES_BLOCK_SIZE..].copy_from_slice(&encrypted_data);
        Ok(encrypted)
    }

    /// Derives and validates a local-storage key.
    ///
    /// # Errors
    ///
    /// Returns an error when key derivation or authorization key validation
    /// fails.
    pub fn create_local_key(salt: &[u8], passcode: &[u8]) -> Result<AuthKey> {
        let key = CryptoUtils::derive_local_key(passcode, salt)?;
        AuthKey::new(key, AuthKeyType::Local, 0)
    }

    /// Computes Telegram Desktop's file key for an account data name.
    pub fn compute_data_name_key(key_file: &str) -> u64 {
        let mut hasher = Md5::new();
        hasher.update(key_file.as_bytes());
        let hash = hasher.finalize();
        u64::from_le_bytes(hash[..8].try_into().expect("MD5 has at least eight bytes"))
    }

    /// Matches Telegram Desktop's low-nibble-first `ToFilePart` representation.
    pub fn to_file_part(mut key: u64) -> String {
        let mut result = String::with_capacity(16);
        for _ in 0..16 {
            let nibble = (key & 0x0f) as u8;
            result.push(if nibble < 10 {
                (b'0' + nibble) as char
            } else {
                (b'A' + nibble - 10) as char
            });
            key >>= 4;
        }
        result
    }

    /// Reads and authenticates a Telegram Desktop storage file.
    ///
    /// # Errors
    ///
    /// Returns an error for an unsafe file name, a missing file, an I/O failure,
    /// an excessive file size, an invalid header, or a checksum mismatch.
    pub fn read_tdf_file(base_path: &Path, base_name: &str) -> Result<(Vec<u8>, u32)> {
        validate_file_name(base_name)?;
        let mut candidates = vec![
            base_path.join(format!("{base_name}s")),
            base_path.join(format!("{base_name}0")),
            base_path.join(format!("{base_name}1")),
            base_path.join(base_name),
        ];
        candidates.retain(|path| path.is_file());
        if candidates.is_empty() {
            return Err(OpenteleError::InvalidTData(format!(
                "storage file {base_name} was not found in {}",
                base_path.display()
            )));
        }

        let mut last_error = None;
        for path in candidates {
            match read_tdf_path(&path) {
                Ok(value) => return Ok(value),
                Err(error) => last_error = Some(error),
            }
        }
        Err(last_error.expect("at least one storage candidate exists"))
    }
}

/// Incrementally builds one authenticated TDF file.
pub struct FileWriteDescriptor {
    file_name: String,
    base_path: PathBuf,
    data: Vec<u8>,
    md5_data: Vec<u8>,
    full_size: u32,
}

impl FileWriteDescriptor {
    /// Starts a descriptor for a single file name below `base_path`.
    ///
    /// # Errors
    ///
    /// Returns an error when `file_name` is empty or contains path components.
    pub fn new(file_name: &str, base_path: &Path) -> Result<Self> {
        validate_file_name(file_name)?;
        Ok(Self {
            file_name: file_name.to_string(),
            base_path: base_path.to_path_buf(),
            data: Vec::new(),
            md5_data: Vec::new(),
            full_size: 0,
        })
    }

    /// Appends one Qt-compatible byte-array field.
    ///
    /// # Errors
    ///
    /// Returns an error when the payload or accumulated TDF data exceeds the
    /// `u32` length range.
    pub fn write_data(&mut self, payload: &[u8]) -> Result<()> {
        let length = u32::try_from(payload.len()).map_err(|_| {
            OpenteleError::InvalidArgument("TDF field is larger than u32::MAX".into())
        })?;
        self.full_size = self
            .full_size
            .checked_add(4)
            .and_then(|size| size.checked_add(length))
            .ok_or_else(|| {
                OpenteleError::InvalidArgument("TDF file is larger than u32::MAX".into())
            })?;
        let length_be = length.to_be_bytes();
        self.data.extend_from_slice(&length_be);
        self.data.extend_from_slice(payload);
        self.md5_data.extend_from_slice(&length_be);
        self.md5_data.extend_from_slice(payload);
        Ok(())
    }

    /// Encrypts and appends one byte-array field.
    ///
    /// # Errors
    ///
    /// Returns an error when encryption fails or the resulting field exceeds
    /// the supported TDF size range.
    pub fn write_encrypted(&mut self, data: &[u8], key: &AuthKey) -> Result<()> {
        self.write_data(&Storage::prepare_encrypted(data, key)?)
    }

    /// Authenticates and atomically writes the completed TDF file.
    ///
    /// # Errors
    ///
    /// Returns an error when the TDF exceeds its defensive size limit, an I/O
    /// operation fails, or the destination cannot be replaced safely.
    pub fn finish(mut self, app_version: u32) -> Result<PathBuf> {
        self.md5_data
            .extend_from_slice(&self.full_size.to_le_bytes());
        self.md5_data.extend_from_slice(&app_version.to_le_bytes());
        self.md5_data.extend_from_slice(TDF_MAGIC);
        let signature = Md5::digest(&self.md5_data);

        let total_size = 8u64 + self.data.len() as u64 + AES_BLOCK_SIZE as u64;
        if total_size > MAX_TDF_FILE_SIZE {
            return Err(OpenteleError::SizeLimit {
                actual: total_size,
                maximum: MAX_TDF_FILE_SIZE,
            });
        }

        std::fs::create_dir_all(&self.base_path)?;
        let destination = self.base_path.join(&self.file_name);
        let temporary = temporary_path(&self.base_path, &self.file_name);
        let mut file = OpenOptions::new()
            .write(true)
            .create_new(true)
            .open(&temporary)?;
        file.write_all(TDF_MAGIC)?;
        file.write_all(&app_version.to_le_bytes())?;
        file.write_all(&self.data)?;
        file.write_all(&signature)?;
        file.sync_all()?;
        drop(file);
        replace_file(&temporary, &destination)?;
        Ok(destination)
    }
}

/// Rejects empty names and names that could escape the storage directory.
fn validate_file_name(file_name: &str) -> Result<()> {
    let path = Path::new(file_name);
    if file_name.is_empty()
        || path.file_name().and_then(|name| name.to_str()) != Some(file_name)
        || matches!(file_name, "." | "..")
    {
        return Err(OpenteleError::InvalidArgument(format!(
            "storage file name must not contain path components: {file_name:?}"
        )));
    }
    Ok(())
}

/// Reads one exact TDF path and verifies its header, bounds, and checksum.
fn read_tdf_path(path: &Path) -> Result<(Vec<u8>, u32)> {
    let metadata = path.metadata()?;
    if metadata.len() > MAX_TDF_FILE_SIZE {
        return Err(OpenteleError::SizeLimit {
            actual: metadata.len(),
            maximum: MAX_TDF_FILE_SIZE,
        });
    }
    if metadata.len() < 24 {
        return Err(OpenteleError::InvalidTData(format!(
            "{} is too small to be a TDF file",
            path.display()
        )));
    }

    let mut bytes = Vec::with_capacity(metadata.len() as usize);
    File::open(path)?.read_to_end(&mut bytes)?;
    if &bytes[..4] != TDF_MAGIC {
        return Err(OpenteleError::InvalidTData(format!(
            "invalid TDF magic in {}",
            path.display()
        )));
    }
    let version = u32::from_le_bytes(bytes[4..8].try_into().expect("TDF header is complete"));
    let signature_offset = bytes.len() - AES_BLOCK_SIZE;
    let payload = &bytes[8..signature_offset];
    let signature = &bytes[signature_offset..];

    let mut signed = Vec::with_capacity(payload.len() + 12);
    signed.extend_from_slice(payload);
    let payload_len = u32::try_from(payload.len())
        .map_err(|_| OpenteleError::InvalidTData("TDF payload exceeds u32::MAX".into()))?;
    signed.extend_from_slice(&payload_len.to_le_bytes());
    signed.extend_from_slice(&version.to_le_bytes());
    signed.extend_from_slice(TDF_MAGIC);
    if Md5::digest(&signed).as_slice() != signature {
        return Err(OpenteleError::InvalidTData(format!(
            "TDF checksum mismatch in {}",
            path.display()
        )));
    }
    Ok((payload.to_vec(), version))
}

/// Generates an unused temporary path within a TDF destination directory.
fn temporary_path(base_path: &Path, file_name: &str) -> PathBuf {
    loop {
        let suffix = rand::random::<u64>();
        let candidate = base_path.join(format!(".{file_name}.{suffix:016x}.tmp"));
        if !candidate.exists() {
            return candidate;
        }
    }
}

/// Replaces a TDF destination and restores its backup if replacement fails.
fn replace_file(temporary: &Path, destination: &Path) -> Result<()> {
    if !destination.exists() {
        std::fs::rename(temporary, destination)?;
        return Ok(());
    }

    let file_name = destination
        .file_name()
        .and_then(|name| name.to_str())
        .ok_or_else(|| OpenteleError::InvalidArgument("destination is not valid UTF-8".into()))?;
    let backup = temporary_path(
        destination.parent().unwrap_or_else(|| Path::new(".")),
        &format!("{file_name}.backup"),
    );
    std::fs::rename(destination, &backup)?;
    match std::fs::rename(temporary, destination) {
        Ok(()) => {
            std::fs::remove_file(backup)?;
            Ok(())
        }
        Err(error) => {
            let _ = std::fs::rename(&backup, destination);
            Err(error.into())
        }
    }
}