aspose-cells-foss 25.12.1__py3-none-any.whl → 26.2.2__py3-none-any.whl

aspose_cells/document_properties.py

@@ -0,0 +1,356 @@
+"""
+Aspose.Cells for Python - Document Properties Module
+
+This module provides classes for document-level properties according to ECMA-376 specification.
+These properties are stored in docProps/core.xml and docProps/app.xml files.
+
+ECMA-376 Part 2: Open Packaging Conventions - Core Properties
+ECMA-376 Part 1: Extended Properties (docProps/app.xml)
+"""
+
+from datetime import datetime
+
+
+class CoreProperties:
+    """
+    Represents core document properties stored in docProps/core.xml.
+
+    Uses Dublin Core metadata elements and OPC core properties.
+
+    ECMA-376 Part 2, Section 11 - Core Properties
+
+    Examples:
+        >>> wb.document_properties.core.title = "Sales Report"
+        >>> wb.document_properties.core.creator = "John Doe"
+        >>> wb.document_properties.core.subject = "Q4 2024 Sales"
+    """
+
+    def __init__(self):
+        self._title = None
+        self._subject = None
+        self._creator = None
+        self._keywords = None
+        self._description = None
+        self._last_modified_by = None
+        self._revision = None
+        self._created = None
+        self._modified = None
+        self._category = None
+        self._content_status = None
+        self._content_type = None
+        self._identifier = None
+        self._language = None
+        self._version = None
+
+    @property
+    def title(self):
+        """Document title (dc:title)."""
+        return self._title
+
+    @title.setter
+    def title(self, value):
+        self._title = value
+
+    @property
+    def subject(self):
+        """Document subject (dc:subject)."""
+        return self._subject
+
+    @subject.setter
+    def subject(self, value):
+        self._subject = value
+
+    @property
+    def creator(self):
+        """Document creator/author (dc:creator)."""
+        return self._creator
+
+    @creator.setter
+    def creator(self, value):
+        self._creator = value
+
+    @property
+    def keywords(self):
+        """Keywords associated with the document (cp:keywords)."""
+        return self._keywords
+
+    @keywords.setter
+    def keywords(self, value):
+        self._keywords = value
+
+    @property
+    def description(self):
+        """Document description/comments (dc:description)."""
+        return self._description
+
+    @description.setter
+    def description(self, value):
+        self._description = value
+
+    @property
+    def last_modified_by(self):
+        """Name of person who last modified the document (cp:lastModifiedBy)."""
+        return self._last_modified_by
+
+    @last_modified_by.setter
+    def last_modified_by(self, value):
+        self._last_modified_by = value
+
+    @property
+    def revision(self):
+        """Revision number (cp:revision)."""
+        return self._revision
+
+    @revision.setter
+    def revision(self, value):
+        self._revision = value
+
+    @property
+    def created(self):
+        """Document creation date (dcterms:created)."""
+        return self._created
+
+    @created.setter
+    def created(self, value):
+        self._created = value
+
+    @property
+    def modified(self):
+        """Document last modification date (dcterms:modified)."""
+        return self._modified
+
+    @modified.setter
+    def modified(self, value):
+        self._modified = value
+
+    @property
+    def category(self):
+        """Document category (cp:category)."""
+        return self._category
+
+    @category.setter
+    def category(self, value):
+        self._category = value
+
+    @property
+    def content_status(self):
+        """Content status such as Draft, Final (cp:contentStatus)."""
+        return self._content_status
+
+    @content_status.setter
+    def content_status(self, value):
+        self._content_status = value
+
+
+class ExtendedProperties:
+    """
+    Represents extended/application properties stored in docProps/app.xml.
+
+    ECMA-376 Part 1, Section 22.2 - Extended Properties
+
+    Examples:
+        >>> wb.document_properties.extended.application = "Microsoft Excel"
+        >>> wb.document_properties.extended.company = "Acme Corp"
+    """
+
+    def __init__(self):
+        self._application = "Microsoft Excel"
+        self._app_version = None
+        self._company = None
+        self._manager = None
+        self._doc_security = 0
+        self._hyperlink_base = None
+        self._scale_crop = False
+        self._links_up_to_date = False
+        self._shared_doc = False
+
+    @property
+    def application(self):
+        """Name of the application that created the document."""
+        return self._application
+
+    @application.setter
+    def application(self, value):
+        self._application = value
+
+    @property
+    def app_version(self):
+        """Version of the application that created the document."""
+        return self._app_version
+
+    @app_version.setter
+    def app_version(self, value):
+        self._app_version = value
+
+    @property
+    def company(self):
+        """Company or organization name."""
+        return self._company
+
+    @company.setter
+    def company(self, value):
+        self._company = value
+
+    @property
+    def manager(self):
+        """Manager associated with the document."""
+        return self._manager
+
+    @manager.setter
+    def manager(self, value):
+        self._manager = value
+
+    @property
+    def doc_security(self):
+        """Document security level (0=none, 1=password protected, etc.)."""
+        return self._doc_security
+
+    @doc_security.setter
+    def doc_security(self, value):
+        self._doc_security = value
+
+    @property
+    def hyperlink_base(self):
+        """Base URL for relative hyperlinks."""
+        return self._hyperlink_base
+
+    @hyperlink_base.setter
+    def hyperlink_base(self, value):
+        self._hyperlink_base = value
+
+    @property
+    def scale_crop(self):
+        """Whether to scale or crop document thumbnail."""
+        return self._scale_crop
+
+    @scale_crop.setter
+    def scale_crop(self, value):
+        self._scale_crop = value
+
+    @property
+    def links_up_to_date(self):
+        """Whether hyperlinks are up to date."""
+        return self._links_up_to_date
+
+    @links_up_to_date.setter
+    def links_up_to_date(self, value):
+        self._links_up_to_date = value
+
+    @property
+    def shared_doc(self):
+        """Whether the document is shared."""
+        return self._shared_doc
+
+    @shared_doc.setter
+    def shared_doc(self, value):
+        self._shared_doc = value
+
+
+class DocumentProperties:
+    """
+    Container for all document-level properties.
+
+    This includes both core properties (docProps/core.xml) and
+    extended properties (docProps/app.xml).
+
+    Examples:
+        >>> wb.document_properties.core.title = "Sales Report"
+        >>> wb.document_properties.core.creator = "John Doe"
+        >>> wb.document_properties.extended.company = "Acme Corp"
+    """
+
+    def __init__(self):
+        self._core = CoreProperties()
+        self._extended = ExtendedProperties()
+
+    @property
+    def core(self):
+        """Gets core document properties (stored in docProps/core.xml)."""
+        return self._core
+
+    @property
+    def extended(self):
+        """Gets extended/application properties (stored in docProps/app.xml)."""
+        return self._extended
+
+    # Convenience properties that map to core properties
+    @property
+    def title(self):
+        """Document title."""
+        return self._core.title
+
+    @title.setter
+    def title(self, value):
+        self._core.title = value
+
+    @property
+    def subject(self):
+        """Document subject."""
+        return self._core.subject
+
+    @subject.setter
+    def subject(self, value):
+        self._core.subject = value
+
+    @property
+    def author(self):
+        """Document author (alias for creator)."""
+        return self._core.creator
+
+    @author.setter
+    def author(self, value):
+        self._core.creator = value
+
+    @property
+    def creator(self):
+        """Document creator."""
+        return self._core.creator
+
+    @creator.setter
+    def creator(self, value):
+        self._core.creator = value
+
+    @property
+    def keywords(self):
+        """Document keywords."""
+        return self._core.keywords
+
+    @keywords.setter
+    def keywords(self, value):
+        self._core.keywords = value
+
+    @property
+    def comments(self):
+        """Document comments (alias for description)."""
+        return self._core.description
+
+    @comments.setter
+    def comments(self, value):
+        self._core.description = value
+
+    @property
+    def category(self):
+        """Document category."""
+        return self._core.category
+
+    @category.setter
+    def category(self, value):
+        self._core.category = value
+
+    @property
+    def company(self):
+        """Company name."""
+        return self._extended.company
+
+    @company.setter
+    def company(self, value):
+        self._extended.company = value
+
+    @property
+    def manager(self):
+        """Manager name."""
+        return self._extended.manager
+
+    @manager.setter
+    def manager(self, value):
+        self._extended.manager = value

aspose_cells/encryption_crypto.py

@@ -0,0 +1,247 @@
+"""
+XLSX Encryption Cryptographic Operations
+
+This module implements cryptographic operations for XLSX encryption/decryption
+according to MS-OFFCRYPTO (Agile Encryption).
+"""
+
+import hashlib
+import os
+import struct
+from Crypto.Cipher import AES
+
+
+class PasswordDerivation:
+    """Password derivation helpers for Agile encryption."""
+
+    @staticmethod
+    def derive_hash_agile(password, salt, hash_algorithm, spin_count):
+        """
+        Derive H_n for Agile encryption (MS-OFFCRYPTO 2.3.4.11).
+
+        H_0 = Hash(salt + password)
+        H_i = Hash(i + H_{i-1}) for i in [0, spin_count)
+        """
+        password_bytes = password.encode('utf-16le')
+        hash_func_name = hash_algorithm.algorithm_name.lower()
+
+        h = hashlib.new(hash_func_name)
+        h.update(salt)
+        h.update(password_bytes)
+        current = h.digest()
+
+        for i in range(spin_count):
+            h = hashlib.new(hash_func_name)
+            h.update(struct.pack('<I', i))
+            h.update(current)
+            current = h.digest()
+
+        return current
+
+    @staticmethod
+    def derive_key_with_block_key(h_base, block_key, hash_algorithm, key_bits):
+        """
+        Derive key from H_n and block key (MS-OFFCRYPTO 2.3.4.11).
+        """
+        hash_func_name = hash_algorithm.algorithm_name.lower()
+        h = hashlib.new(hash_func_name)
+        h.update(h_base)
+        h.update(block_key)
+        derived = h.digest()
+
+        key_bytes = key_bits // 8
+        if len(derived) >= key_bytes:
+            return derived[:key_bytes]
+        return derived + (b'\x36' * (key_bytes - len(derived)))
+
+    @staticmethod
+    def derive_iv_agile(salt, block_key, hash_algorithm, block_size):
+        """
+        Derive IV for Agile encryption (MS-OFFCRYPTO 2.3.4.12).
+
+        If block_key is None, IV = salt (padded/truncated to block_size).
+        Otherwise IV = Hash(salt + block_key), padded/truncated to block_size.
+        """
+        if block_key is None:
+            iv = salt
+        else:
+            hash_func_name = hash_algorithm.algorithm_name.lower()
+            h = hashlib.new(hash_func_name)
+            h.update(salt)
+            h.update(block_key)
+            iv = h.digest()
+
+        if len(iv) >= block_size:
+            return iv[:block_size]
+        return iv + (b'\x36' * (block_size - len(iv)))
+
+
+class EncryptionVerifier:
+    """Encryption verifier generation and validation."""
+
+    BLOCK_KEY_VERIFIER = bytes.fromhex('fea7d2763b4b9e79')
+    BLOCK_KEY_VERIFIER_HASH = bytes.fromhex('d7aa0f6d3061344e')
+    BLOCK_KEY_KEYVALUE = bytes.fromhex('146e0be7abacd0d6')
+    BLOCK_KEY_DATA_INTEGRITY_KEY = bytes.fromhex('5fb2ad010cb9e1f6')
+    BLOCK_KEY_DATA_INTEGRITY_VALUE = bytes.fromhex('a0677f02b22c8433')
+
+    @staticmethod
+    def _pad_zero(data, block_size):
+        if len(data) % block_size == 0:
+            return data
+        pad_len = block_size - (len(data) % block_size)
+        return data + (b'\x00' * pad_len)
+
+    @staticmethod
+    def generate_verifier_agile(password, salt, hash_algorithm, cipher_algorithm, spin_count):
+        """
+        Generate PasswordKeyEncryptor fields (MS-OFFCRYPTO 2.3.4.13).
+        """
+        verifier_input = os.urandom(16)
+        hash_func_name = hash_algorithm.algorithm_name.lower()
+        verifier_hash = hashlib.new(hash_func_name, verifier_input).digest()
+
+        h_base = PasswordDerivation.derive_hash_agile(
+            password, salt, hash_algorithm, spin_count
+        )
+
+        verifier_key = PasswordDerivation.derive_key_with_block_key(
+            h_base, EncryptionVerifier.BLOCK_KEY_VERIFIER,
+            hash_algorithm, cipher_algorithm.key_bits
+        )
+        iv = PasswordDerivation.derive_iv_agile(
+            salt, None, hash_algorithm, cipher_algorithm.block_size
+        )
+        encrypted_verifier = AES.new(verifier_key, AES.MODE_CBC, iv).encrypt(verifier_input)
+
+        hash_key = PasswordDerivation.derive_key_with_block_key(
+            h_base, EncryptionVerifier.BLOCK_KEY_VERIFIER_HASH,
+            hash_algorithm, cipher_algorithm.key_bits
+        )
+        verifier_hash_padded = EncryptionVerifier._pad_zero(
+            verifier_hash, cipher_algorithm.block_size
+        )
+        encrypted_verifier_hash = AES.new(hash_key, AES.MODE_CBC, iv).encrypt(verifier_hash_padded)
+
+        key_value = os.urandom(cipher_algorithm.key_bits // 8)
+        key_value_key = PasswordDerivation.derive_key_with_block_key(
+            h_base, EncryptionVerifier.BLOCK_KEY_KEYVALUE,
+            hash_algorithm, cipher_algorithm.key_bits
+        )
+        encrypted_key_value = AES.new(key_value_key, AES.MODE_CBC, iv).encrypt(key_value)
+
+        return {
+            'verifier_salt': salt,
+            'encrypted_verifier': encrypted_verifier,
+            'encrypted_verifier_hash': encrypted_verifier_hash,
+            'encrypted_key_value': encrypted_key_value,
+            'key_value': key_value,
+            'password_hash': h_base
+        }
+
+    @staticmethod
+    def verify_password_agile(password, salt, encrypted_verifier, encrypted_verifier_hash,
+                              hash_algorithm, cipher_algorithm, spin_count):
+        """
+        Verify password for Agile encryption (MS-OFFCRYPTO 2.3.4.13).
+
+        Returns:
+            H_n if password is correct, None otherwise.
+        """
+        try:
+            h_base = PasswordDerivation.derive_hash_agile(
+                password, salt, hash_algorithm, spin_count
+            )
+
+            verifier_key = PasswordDerivation.derive_key_with_block_key(
+                h_base, EncryptionVerifier.BLOCK_KEY_VERIFIER,
+                hash_algorithm, cipher_algorithm.key_bits
+            )
+            iv = PasswordDerivation.derive_iv_agile(
+                salt, None, hash_algorithm, cipher_algorithm.block_size
+            )
+            decrypted_verifier = AES.new(verifier_key, AES.MODE_CBC, iv).decrypt(encrypted_verifier)
+
+            hash_func_name = hash_algorithm.algorithm_name.lower()
+            computed_hash = hashlib.new(hash_func_name, decrypted_verifier).digest()
+
+            hash_key = PasswordDerivation.derive_key_with_block_key(
+                h_base, EncryptionVerifier.BLOCK_KEY_VERIFIER_HASH,
+                hash_algorithm, cipher_algorithm.key_bits
+            )
+            decrypted_hash = AES.new(hash_key, AES.MODE_CBC, iv).decrypt(encrypted_verifier_hash)
+
+            if computed_hash != decrypted_hash[:len(computed_hash)]:
+                return None
+
+            return h_base
+        except Exception:
+            return None
+
+    @staticmethod
+    def decrypt_key_value(h_base, key_salt, encrypted_key_value, hash_algorithm, cipher_algorithm):
+        """Decrypt intermediate key value (MS-OFFCRYPTO 2.3.4.13)."""
+        key_value_key = PasswordDerivation.derive_key_with_block_key(
+            h_base, EncryptionVerifier.BLOCK_KEY_KEYVALUE,
+            hash_algorithm, cipher_algorithm.key_bits
+        )
+        iv = PasswordDerivation.derive_iv_agile(
+            key_salt, None, hash_algorithm, cipher_algorithm.block_size
+        )
+        return AES.new(key_value_key, AES.MODE_CBC, iv).decrypt(encrypted_key_value)
+
+    @staticmethod
+    def decrypt_data_integrity(secret_key, package_salt, encrypted_hmac_key, encrypted_hmac_value,
+                               hash_algorithm, block_size, hash_size):
+        """Decrypt HMAC key and value (MS-OFFCRYPTO 2.3.4.14)."""
+        iv_key = PasswordDerivation.derive_iv_agile(
+            package_salt, EncryptionVerifier.BLOCK_KEY_DATA_INTEGRITY_KEY,
+            hash_algorithm, block_size
+        )
+        iv_val = PasswordDerivation.derive_iv_agile(
+            package_salt, EncryptionVerifier.BLOCK_KEY_DATA_INTEGRITY_VALUE,
+            hash_algorithm, block_size
+        )
+        hmac_key = AES.new(secret_key, AES.MODE_CBC, iv_key).decrypt(encrypted_hmac_key)
+        hmac_value = AES.new(secret_key, AES.MODE_CBC, iv_val).decrypt(encrypted_hmac_value)
+        return hmac_key[:hash_size], hmac_value[:hash_size]
+
+
+class PackageEncryption:
+    """Package data encryption and decryption."""
+
+    @staticmethod
+    def encrypt_package_agile(data, key, package_salt, hash_algorithm, block_size):
+        """Encrypt package data using Agile encryption (MS-OFFCRYPTO 2.3.4.15)."""
+        encrypted = bytearray()
+        segment_size = 4096
+
+        for segment_index in range(0, len(data), segment_size):
+            chunk = data[segment_index:segment_index + segment_size]
+            block_key = struct.pack('<I', segment_index // segment_size)
+            iv = PasswordDerivation.derive_iv_agile(
+                package_salt, block_key, hash_algorithm, block_size
+            )
+            if len(chunk) % block_size != 0:
+                chunk = chunk + (b'\x00' * (block_size - (len(chunk) % block_size)))
+            cipher = AES.new(key, AES.MODE_CBC, iv)
+            encrypted.extend(cipher.encrypt(chunk))
+
+        return bytes(encrypted)
+
+    @staticmethod
+    def decrypt_package_agile(encrypted_data, key, package_salt, hash_algorithm, block_size):
+        """Decrypt package data using Agile encryption (MS-OFFCRYPTO 2.3.4.15)."""
+        decrypted = bytearray()
+        segment_size = 4096
+
+        for segment_index in range(0, len(encrypted_data), segment_size):
+            chunk = encrypted_data[segment_index:segment_index + segment_size]
+            block_key = struct.pack('<I', segment_index // segment_size)
+            iv = PasswordDerivation.derive_iv_agile(
+                package_salt, block_key, hash_algorithm, block_size
+            )
+            cipher = AES.new(key, AES.MODE_CBC, iv)
+            decrypted.extend(cipher.decrypt(chunk))
+
+        return bytes(decrypted)