msoffcrypto-tool is a Python tool and library for decrypting and encrypting MS Office files using a password or other keys.
- Installation
- Examples
- Supported encryption methods
- Tests
- Todo
- Resources
- Use cases and mentions
- Contributors
- Credits
pip install msoffcrypto-tool
Specify the password with -p
flag:
msoffcrypto-tool encrypted.docx decrypted.docx -p Passw0rd
Password is prompted if you omit the password argument value:
$ msoffcrypto-tool encrypted.docx decrypted.docx -p
Password:
To check if the file is encrypted or not, use -t
flag:
msoffcrypto-tool document.doc --test -v
It returns 1
if the file is encrypted, 0
if not.
Important
Encryption feature is experimental. Please use it at your own risk.
To password-protect a document, use -e
flag along with -p
flag:
msoffcrypto-tool -e -p Passw0rd plain.docx encrypted.docx
Password and more key types are supported with library functions.
Basic usage:
import msoffcrypto
encrypted = open("encrypted.docx", "rb")
file = msoffcrypto.OfficeFile(encrypted)
file.load_key(password="Passw0rd") # Use password
with open("decrypted.docx", "wb") as f:
file.decrypt(f)
encrypted.close()
In-memory:
import msoffcrypto
import io
import pandas as pd
decrypted = io.BytesIO()
with open("encrypted.xlsx", "rb") as f:
file = msoffcrypto.OfficeFile(f)
file.load_key(password="Passw0rd") # Use password
file.decrypt(decrypted)
df = pd.read_excel(decrypted)
print(df)
Advanced usage:
# Verify password before decryption (default: False)
# The ECMA-376 Agile/Standard crypto system allows one to know whether the supplied password is correct before actually decrypting the file
# Currently, the verify_password option is only meaningful for ECMA-376 Agile/Standard Encryption
file.load_key(password="Passw0rd", verify_password=True)
# Use private key
file.load_key(private_key=open("priv.pem", "rb"))
# Use intermediate key (secretKey)
file.load_key(secret_key=binascii.unhexlify("AE8C36E68B4BB9EA46E5544A5FDB6693875B2FDE1507CBC65C8BCF99E25C2562"))
# Check the HMAC of the data payload before decryption (default: False)
# Currently, the verify_integrity option is only meaningful for ECMA-376 Agile Encryption
file.decrypt(open("decrypted.docx", "wb"), verify_integrity=True)
Supported key types are
- Passwords
- Intermediate keys (optional)
- Private keys used for generating escrow keys (escrow certificates) (optional)
See also "Backdooring MS Office documents with secret master keys" for more information on the key types.
Important
Encryption feature is experimental. Please use it at your own risk.
Basic usage:
from msoffcrypto.format.ooxml import OOXMLFile
plain = open("plain.docx", "rb")
file = OOXMLFile(plain)
with open("encrypted.docx", "wb") as f:
file.encrypt("Passw0rd", f)
plain.close()
In-memory:
from msoffcrypto.format.ooxml import OOXMLFile
import io
encrypted = io.BytesIO()
with open("plain.xlsx", "rb") as f:
file = OOXMLFile(f)
file.encrypt("Passw0rd", encrypted)
# Do stuff with encrypted buffer; it contains an OLE container with an encrypted stream
...
- ECMA-376 (Agile Encryption/Standard Encryption)
- MS-DOCX (OOXML) (Word 2007-)
- MS-XLSX (OOXML) (Excel 2007-)
- MS-PPTX (OOXML) (PowerPoint 2007-)
- Office Binary Document RC4 CryptoAPI
- MS-DOC (Word 2002, 2003, 2004)
- MS-XLS (Excel 2002, 2003, 2007, 2010) (experimental)
- MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental)
- Office Binary Document RC4
- MS-DOC (Word 97, 98, 2000)
- MS-XLS (Excel 97, 98, 2000) (experimental)
- ECMA-376 (Extensible Encryption)
- XOR Obfuscation
- MS-XLS (Excel 2002, 2003) (experimental)
- MS-DOC (Word 2002, 2003, 2004?)
- Word 95 Encryption (Word 95 and prior)
- Excel 95 Encryption (Excel 95 and prior)
- PowerPoint 95 Encryption (PowerPoint 95 and prior)
PRs are welcome!
poetry install
poetry run coverage run -m pytest -v
- Add tests
- Support decryption with passwords
- Support older encryption schemes
- Add function-level tests
- Add API documents
- Publish to PyPI
- Add decryption tests for various file formats
- Integrate with more comprehensive projects handling MS Office files (such as oletools?) if possible
- Add the password prompt mode for CLI
- Improve error types (v4.12.0)
- Add type hints
- Introduce something like
ctypes.Structure
- Support OOXML encryption
- Support other encryption
- Isolate parser
- Redesign APIs (v6.0.0)
- "Backdooring MS Office documents with secret master keys" http://secuinside.com/archive/2015/2015-1-9.pdf
- Technical Documents https://msdn.microsoft.com/en-us/library/cc313105.aspx
- [MS-OFFCRYPTO] Agile Encryption https://msdn.microsoft.com/en-us/library/dd949735(v=office.12).aspx
- [MS-OFFDI] Microsoft Office File Format Documentation Introduction https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offdi/24ed256c-eb5b-494e-b4f6-fb696ad2b4dc
- LibreOffice/core https://github.com/LibreOffice/core
- LibreOffice/mso-dumper https://github.com/LibreOffice/mso-dumper
- wvDecrypt http://www.skynet.ie/~caolan/Packages/wvDecrypt.html
- Microsoft Office password protection - Wikipedia https://en.wikipedia.org/wiki/Microsoft_Office_password_protection#History_of_Microsoft_Encryption_password
- office2john.py https://github.com/magnumripper/JohnTheRipper/blob/bleeding-jumbo/run/office2john.py
- herumi/msoffice https://github.com/herumi/msoffice
- DocRecrypt https://blogs.technet.microsoft.com/office_resource_kit/2013/01/23/now-you-can-reset-or-remove-a-password-from-a-word-excel-or-powerpoint-filewith-office-2013/
- Apache POI - the Java API for Microsoft Documents https://poi.apache.org/
- https://repology.org/project/python:msoffcrypto-tool/versions (kudos to maintainers!)
- Workato https://docs.workato.com/connectors/python.html#supported-features
- Check Point https://www.checkpoint.com/about-us/copyright-and-trademarks/
- https://github.com/jbremer/sflock/commit/3f6a96abe1dbb4405e4fb7fd0d16863f634b09fb
- https://isc.sans.edu/forums/diary/Video+Analyzing+Encrypted+Malicious+Office+Documents/24572/
- https://github.com/shombo/cyberstakes-writeps-2018/tree/master/word_up
- https://github.com/willi123yao/Cyberthon2020_Writeups/blob/master/csit/Lost_Magic
- https://github.com/dtjohnson/xlsx-populate
- https://github.com/opendocument-app/OpenDocument.core/blob/233663b039/src/internal/ooxml/ooxml_crypto.h
- https://github.com/jaydadhania08/PHPDecryptXLSXWithPassword
- https://github.com/epicentre-msf/rpxl
- Excel、データ整理&分析、画像処理の自動化ワザを完全網羅! 超速Python仕事術大全 (伊沢剛, 2022)
- "Analyse de documents malveillants en 2021", MISC Hors-série N° 24, "Reverse engineering : apprenez à analyser des binaires" (Lagadec Philippe, 2021)
- シゴトがはかどる Python自動処理の教科書 (クジラ飛行机, 2020)
- The sample file for XOR Obfuscation is from: https://github.com/openwall/john-samples/tree/main/Office/Office_Secrets