Need help with msoffcrypto-tool?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

nolze
242 Stars 60 Forks MIT License 226 Commits 4 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

msoffcrypto-tool

PyPI 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.

Basic usage:

import msoffcrypto

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

Use password

file.load_key(password="Passw0rd")

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

Basic usage (in-memory):

import msoffcrypto
import io
import pandas as pd

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

Use password

file.load_key(password="Passw0rd")

decrypted = io.BytesIO() 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

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

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

Resources

Alternatives

Use cases and mentions

Contributors

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.