Skip to main content

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

Project description

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.

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

  • <input type="checkbox" checked="" disabled="" /> ECMA-376 (Agile Encryption/Standard Encryption)
    • <input type="checkbox" checked="" disabled="" /> MS-DOCX (OOXML) (Word 2007-2016)
    • <input type="checkbox" checked="" disabled="" /> MS-XLSX (OOXML) (Excel 2007-2016)
    • <input type="checkbox" checked="" disabled="" /> MS-PPTX (OOXML) (PowerPoint 2007-2016)
  • <input type="checkbox" checked="" disabled="" /> Office Binary Document RC4 CryptoAPI
    • <input type="checkbox" checked="" disabled="" /> MS-DOC (Word 2002, 2003, 2004)
    • <input type="checkbox" checked="" disabled="" /> MS-XLS (Excel 2002, 2003, 2004) (experimental)
    • <input type="checkbox" checked="" disabled="" /> MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental)
  • <input type="checkbox" checked="" disabled="" /> Office Binary Document RC4
    • <input type="checkbox" checked="" disabled="" /> MS-DOC (Word 97, 98, 2000)
    • <input type="checkbox" checked="" disabled="" /> MS-XLS (Excel 97, 98, 2000) (experimental)
  • <input type="checkbox" disabled="" /> ECMA-376 (Extensible Encryption)
  • <input type="checkbox" disabled="" /> XOR Obfuscation

Other

  • <input type="checkbox" disabled="" /> Word 95 Encryption (Word 95 and prior)
  • <input type="checkbox" disabled="" /> Excel 95 Encryption (Excel 95 and prior)
  • <input type="checkbox" disabled="" /> 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

  • <input type="checkbox" checked="" disabled="" /> Add tests
  • <input type="checkbox" checked="" disabled="" /> Support decryption with passwords
  • <input type="checkbox" checked="" disabled="" /> Support older encryption schemes
  • <input type="checkbox" checked="" disabled="" /> Add function-level tests
  • <input type="checkbox" checked="" disabled="" /> Add API documents
  • <input type="checkbox" checked="" disabled="" /> Publish to PyPI
  • <input type="checkbox" checked="" disabled="" /> Add decryption tests for various file formats
  • <input type="checkbox" checked="" disabled="" /> Integrate with more comprehensive projects handling MS Office files (such as oletools?) if possible
  • <input type="checkbox" checked="" disabled="" /> Add the password prompt mode for CLI
  • <input type="checkbox" disabled="" /> Redesign APIs (v5.0.0)
  • <input type="checkbox" disabled="" /> Improve error types (v5.0.0)
  • <input type="checkbox" disabled="" /> Use a kind of ctypes.Structure
  • <input type="checkbox" disabled="" /> Support encryption

Resources

Alternatives

Use cases and mentions

Contributors

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for msoffcrypto-tool, version 4.11.0
Filename, size File type Python version Upload date Hashes
Filename, size msoffcrypto-tool-4.11.0.tar.gz (211.1 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page