/msoffcrypto-tool

A Python tool and library for decrypting MS Office files with passwords or other keys

Primary LanguagePythonMIT LicenseMIT

msoffcrypto-tool

PyPI version PyPI downloads Build Status Coverage Status Documentation Status

msoffcrypto-tool (formerly ms-offcrypto-tool) is a 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.

import msoffcrypto

file = msoffcrypto.OfficeFile(open("encrypted.docx", "rb"))

# Use password
file.load_key(password="Passw0rd")

# Use private key
# file.load_key(private_key=open("priv.pem", "rb"))
# Use intermediate key (secretKey)
# file.load_key(secret_key=binascii.unhexlify("AE8C36E68B4BB9EA46E5544A5FDB6693875B2FDE1507CBC65C8BCF99E25C2562"))

file.decrypt(open("decrypted.docx", "wb"))

Supported encryption methods

MS-OFFCRYPTO specs

  • ECMA-376 (Agile Encryption/Standard Encryption)
    • MS-DOCX (OOXML) (Word 2007-2016)
    • MS-XLSX (OOXML) (Excel 2007-2016)
    • MS-PPTX (OOXML) (PowerPoint 2007-2016)
  • Office Binary Document RC4 CryptoAPI
    • MS-DOC (Word 2002, 2003, 2004)
    • MS-XLS (Excel 2002, 2003, 2004) (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

Other

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

PRs welcome!

Tests

Tests can be run in various ways:

  • python -m nose -c .noserc
  • nosetests -c .noserc
  • python -m unittest discover
  • python setup.py test
  • ./tests/test_cli.sh

If the cryptography package is not installed, tests are skipped. If you have dependencies installed only for a certain python version, replace "python" with "pythonX.Y" in the above commands.

Todo

  • 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
  • Redesign APIs (v5.0.0)
  • Improve error types (v5.0.0)
  • Use ctypes.Structure
  • Support encryption

See also

Alternatives

Use cases and mentions

Contributors