Skip to main content

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

Project description


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



pip install msoffcrypto-tool


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

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:


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

df = pd.read_excel(decrypted)

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)

# 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


  • 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


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

PRs are welcome!


With coverage and pytest:

poetry install
poetry run coverage run -m pytest -v


  • 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
  • Improve error types (v4.12.0)
  • Redesign APIs (v6.0.0)
  • Introduce something like ctypes.Structure
  • Support encryption
  • Isolate parser



Use cases and mentions


Malware/maldoc analysis


In other languages

In publications


Project details

Download files

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

Source Distribution

msoffcrypto_tool-5.0.1.tar.gz (29.2 kB view hashes)

Uploaded source

Built Distribution

msoffcrypto_tool-5.0.1-py3-none-any.whl (34.0 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page