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
285 Stars 67 Forks MIT License 237 Commits 3 Opened issues

Description

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

Services available

!
?

Need anything else?

Contributors list

# 113,930
Shell
ooxml
Svelte
HTML
198 commits
# 32,846
python3
Linux
Shell
ooxml
11 commits
# 349,014
Shell
Perl
ooxml
pptx
9 commits
# 361,092
TeX
Shell
ooxml
pptx
6 commits
# 299,468
Shell
C
ooxml
decompi...
2 commits
# 116,011
Shell
ooxml
opencl
ripper
2 commits
# 2,190
Django
generic
jython
circlec...
1 commit
# 556,721
Python
Shell
ooxml
pptx
1 commit
# 558,176
Python
Shell
ooxml
pptx
1 commit

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
  • [ ] 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.