Description

# msoffcrypto-tool [](https://pypi.org/project/msoffcrypto-tool/) [](https://pypistats.org/packages/msoffcrypto-tool) [](https://github.com/nolze/msoffcrypto-tool/actions/workflows/ci.yaml) [](https://codecov.io/gh/nolze/msoffcrypto-tool) [](http://msoffcrypto-tool.readthedocs.io/en/latest/?badge=latest) msoffcrypto-tool is a Python tool and library for decrypting and encrypting MS Office files using a password or other keys. ## Contents * [Installation](#installation) * [Examples](#examples) * [Supported encryption methods](#supported-encryption-methods) * [Tests](#tests) * [Todo](#todo) * [Resources](#resources) * [Use cases and mentions](#use-cases-and-mentions) * [Contributors](#contributors) * [Credits](#credits) ## Installation ``` pip install msoffcrypto-tool ``` ## Examples ### As CLI tool (with password) #### Decryption Specify the password with `-p` flag: ``` msoffcrypto-tool encrypted.docx decrypted.docx -p Passw0rd ``` Password is prompted if you omit the password argument value: ```bash $ 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. #### Encryption (OOXML only, experimental) > [!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 ``` ### As library Password and more key types are supported with library functions. #### Decryption Basic usage: ```python 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: ```python 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: ```python # 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"](https://web.archive.org/web/20171008075059/http://secuinside.com/archive/2015/2015-1-9.pdf) for more information on the key types. #### Encryption (OOXML only, experimental) > [!IMPORTANT] > Encryption feature is experimental. Please use it at your own risk. Basic usage: ```python 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: ```python 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 ... ``` ## Supported encryption methods ### MS-OFFCRYPTO specs * [x] ECMA-376 (Agile Encryption/Standard Encryption) * [x] MS-DOCX (OOXML) (Word 2007-) * [x] MS-XLSX (OOXML) (Excel 2007-) * [x] MS-PPTX (OOXML) (PowerPoint 2007-) * [x] Office Binary Document RC4 CryptoAPI * [x] MS-DOC (Word 2002, 2003, 2004) * [x] MS-XLS ([Excel 2002, 2003, 2007, 2010](https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/a3ad4e36-ab66-426c-ba91-b84433312068#Appendix_A_22)) (experimental) * [x] MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental) * [x]