MS Office Crypto Tool

Warnings

• breaking Version 6.0.0 dropped support for Python 3.7 and 3.8. The library now requires Python >= 3.10.
  Fix: Upgrade your Python environment to 3.10 or newer, or pin msoffcrypto-tool to a version < 6.0.0 if legacy Python is unavoidable (e.g., `pip install msoffcrypto-tool<6.0`).
• gotcha Specific decryption features, such as MSOFBA/VBA decryption or files encrypted with scrypt-based keys, require optional dependencies ('lief' and 'pylibscrypt' respectively). Without them, decryption of these specific components might fail or be incomplete.
  Fix: Install the library with the `[all]` extra to include all optional dependencies: `pip install msoffcrypto-tool[all]`.
• gotcha Not all MS Office file types or encryption methods are universally supported. While it handles common OLE-based (.doc, .xls, .ppt) and some OOXML formats (.docx, .xlsx, .pptx) with standard password protection, very old binary formats or newer, less common encryption schemes might not work.
  Fix: Always test with your specific file types. Refer to the GitHub repository's issue tracker or documentation for details on supported formats and limitations.

Install

• pip install msoffcrypto-tool Install core library
• pip install msoffcrypto-tool[all] Install with all optional dependencies

Imports

• OfficeFile

  from msoffcrypto import OfficeFile

• exceptions

  from msoffcrypto import exceptions

  Common exceptions like InvalidKeyError, FileFormatError are available under exceptions.

Quickstart

This quickstart demonstrates the core API for decrypting an MS Office file. It uses an in-memory byte stream to simulate file I/O. Remember to replace the `encrypted_content` with actual data from a real encrypted file for functional decryption. It also shows handling common decryption exceptions.

import io
import os
from msoffcrypto import OfficeFile, exceptions

# --- IMPORTANT ---
# This example demonstrates the API usage. The `encrypted_content` below is
# NOT a real encrypted MS Office file and will not successfully decrypt.
# For actual decryption, replace it with content read from a real encrypted file.

# A minimal OLE header (not a full encrypted file) for API demonstration.
# A real encrypted file starts with this and contains specific crypto structures.
encrypted_content = b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1\x00\x00\x00\x00\x00\x00\x00\x00" \
                    + b"\x00" * 4000 # Placeholder for file content

# Simulate reading an encrypted file
encrypted_file_stream = io.BytesIO(encrypted_content)
# Simulate an output file for decrypted content
decrypted_file_stream = io.BytesIO()

# Get password from environment variable or set a default placeholder
password = os.environ.get('MSOFFCRYPTO_PASSWORD', 'YourStrongPassword') 

try:
    # Initialize OfficeFile with the encrypted stream
    office_file = OfficeFile(encrypted_file_stream)

    # Load the decryption key using the password
    office_file.load_key(password=password)

    # Decrypt the file to the output stream
    office_file.decrypt(decrypted_file_stream)

    print("API usage demonstrated successfully. Output stream has data.")
    # In a real scenario, decrypted_file_stream.getvalue() would contain the decrypted file content.

except exceptions.InvalidKeyError:
    print("Decryption failed: Invalid password.")
except exceptions.FileFormatError as e:
    print(f"Decryption failed: Invalid file format. {e}")
except Exception as e:
    print(f"An unexpected error occurred: {e}")

# Reset stream position if you want to read it again
encrypted_file_stream.seek(0)
decrypted_file_stream.seek(0)