Awesome Open Source
Awesome Open Source

msoffcrypto-tool

PyPI PyPI downloads Build Status Coverage Status Documentation Status

msoffcrypto-tool (formerly ms-offcrypto-tool) is Python tool and library for decrypting encrypted MS Office files with password, intermediate key, or private key which generated its escrow key.

Contents

Install

pip install msoffcrypto-tool

Examples

As CLI tool (with password)

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:

Test if the file is encrypted or not (exit code 0 or 1 is returned):

msoffcrypto-tool document.doc --test -v

As library

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()

Basic usage (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 encryption methods

MS-OFFCRYPTO specs

  • [x] ECMA-376 (Agile Encryption/Standard Encryption)
    • [x] MS-DOCX (OOXML) (Word 2007-2016)
    • [x] MS-XLSX (OOXML) (Excel 2007-2016)
    • [x] MS-PPTX (OOXML) (PowerPoint 2007-2016)
  • [x] Office Binary Document RC4 CryptoAPI
    • [x] MS-DOC (Word 2002, 2003, 2004)
    • [x] MS-XLS (Excel 2002, 2003, 2004) (experimental)
    • [x] MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental)
  • [x] Office Binary Document RC4
    • [x] MS-DOC (Word 97, 98, 2000)
    • [x] MS-XLS (Excel 97, 98, 2000) (experimental)
  • [ ] ECMA-376 (Extensible Encryption)
  • [ ] XOR Obfuscation

Other

  • [ ] Word 95 Encryption (Word 95 and prior)
  • [ ] Excel 95 Encryption (Excel 95 and prior)
  • [ ] PowerPoint 95 Encryption (PowerPoint 95 and prior)

PRs are welcome!

Tests

With coverage and pytest:

poetry install
poetry run coverage run -m pytest -v

Todo

  • [x] Add tests
  • [x] Support decryption with passwords
  • [x] Support older encryption schemes
  • [x] Add function-level tests
  • [x] Add API documents
  • [x] Publish to PyPI
  • [x] Add decryption tests for various file formats
  • [x] Integrate with more comprehensive projects handling MS Office files (such as oletools?) if possible
  • [x] Add the password prompt mode for CLI
  • [x] Improve error types (v4.12.0)
  • [ ] Redesign APIs (v5.0.0)
  • [ ] Introduce something like ctypes.Structure
  • [ ] Support encryption

Resources

Alternatives

Use cases and mentions

General

Malware/maldoc analysis

CTF

In other languages

Contributors


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
python (54,621
command-line (543
encryption (335
xlsx (77
docx (49
decryption (46
doc (32
xls (30
ppt (28