Registry / auth-security / msoffcrypto-tool

msoffcrypto-tool

JSON →
library6.0.0pypypi✓ verified 24d ago

msoffcrypto-tool is a Python library and command-line tool for decrypting and encrypting MS Office files (e.g., .doc, .xls, .ppt, .docx, .xlsx, .pptx) that are protected with a password or other keys. The current version is 6.0.0, released in February 2024. Releases are infrequent but active, addressing security updates and Python version compatibility.

pip install msoffcrypto-tool
INSTALL
IMPORT
SIG · MSOFFCRYPTO-TOOL
M
msoffcrypto-tool
auth-securitypythonv6.0.0
Install
2.5s avg
Import
48ms
Disk
34MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v6.0.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.910 runs
installs and imports cleanly · install 0.0s · import 0.049s · 35.8MB
glibc
py 3.103.910 runs
installs and imports cleanly · install 2.5s · import 0.047s · 36MB
34MB installed
● package 34MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

OfficeFile
from msoffcrypto import OfficeFile
exceptions
from msoffcrypto import exceptions
Common exceptions like InvalidKeyError, FileFormatError are available under exceptions.

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)
msoffcrypto-tool --version
Debug
Known issues
breakingVersion 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`).
affects: >=6.0.0
gotchaSpecific 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]`.
affects: All versions
gotchaNot 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.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'msoffcrypto'
The 'msoffcrypto-tool' Python package is not installed in the environment or the Python interpreter cannot find it.
fix
Install the library using pip: `pip install msoffcrypto-tool`.
msoffcrypto.exceptions.InvalidKeyError
This error occurs when the provided password for decrypting an encrypted Office file is incorrect or cannot be verified.
fix
Verify that the password used with `file.load_key(password='your_password')` is the correct one for the encrypted file. Double-check for typos or case sensitivity.
msoffcrypto.exceptions.FileFormatError: Unrecognized file format
The input file is either not a supported Microsoft Office encrypted file type (e.g., .doc, .xls, .ppt, .docx, .xlsx, .pptx), is corrupted, or its internal structure is not recognized by the library.
fix
Ensure the file is a valid and supported Microsoft Office document and that it is indeed password-protected. Try opening the file manually with the password to confirm its integrity and encryption status. If the file is a very old or very new/uncommon encryption type, it might not be supported by the current version of the library.
Upgrade
Version history
6.0.0latest on PyPI · released Jan 12, 2026
Audit
Dependencies
cryptographyrequiredCore cryptographic operations.
olefilerequiredParsing OLE compound file format.
liefoptionalRequired for MSOFBA / VBA decryption.
pylibscryptoptionalRequired for scrypt-based key encryption.
Agent activity
13 hits · last 30 days
node
10
OpenAI (training)
1
Resources
msoffcrypto-tool — pip install msoffcrypto-tool · libregistry