Home

Awesome

msoffcrypto-tool

PyPI PyPI downloads build Coverage Status Documentation Status

msoffcrypto-tool is a Python tool and library for decrypting and encrypting MS Office files using a password or other keys.

Contents

Installation

pip install msoffcrypto-tool

Examples

As CLI tool (with password)

Decryption

Specify the password with -p flag:

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:

To check if the file is encrypted or not, use -t flag:

msoffcrypto-tool document.doc --test -v

It returns 1 if the file is encrypted, 0 if not.

Encryption (OOXML only, experimental)

[!IMPORTANT] Encryption feature is experimental. Please use it at your own risk.

To password-protect a document, use -e flag along with -p flag:

msoffcrypto-tool -e -p Passw0rd plain.docx encrypted.docx

As library

Password and more key types are supported with library functions.

Decryption

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()

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 key types are

See also "Backdooring MS Office documents with secret master keys" for more information on the key types.

Encryption (OOXML only, experimental)

[!IMPORTANT] Encryption feature is experimental. Please use it at your own risk.

Basic usage:

from msoffcrypto.format.ooxml import OOXMLFile

plain = open("plain.docx", "rb")
file = OOXMLFile(plain)

with open("encrypted.docx", "wb") as f:
    file.encrypt("Passw0rd", f)

plain.close()

In-memory:

from msoffcrypto.format.ooxml import OOXMLFile
import io

encrypted = io.BytesIO()

with open("plain.xlsx", "rb") as f:
    file = OOXMLFile(f)
    file.encrypt("Passw0rd", encrypted)

# Do stuff with encrypted buffer; it contains an OLE container with an encrypted stream
...

Supported encryption methods

MS-OFFCRYPTO specs

Other

PRs are welcome!

Tests

With coverage and pytest:

poetry install
poetry run coverage run -m pytest -v

Todo

Resources

Alternatives

Use cases and mentions

General

<!-- * <https://checkroth.com/unlocking-password-protected-files.html> (outdated) -->

Corporate

Malware/maldoc analysis

CTF

In other languages

In publications

Contributors

Credits