The code on PyPI doesn't match the code in the repository

msoffcrypto-tool

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

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

Passwords
Intermediate keys (optional)
Private keys used for generating escrow keys (escrow certificates) (optional)

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

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

Resources

"Backdooring MS Office documents with secret master keys" http://secuinside.com/archive/2015/2015-1-9.pdf
Technical Documents https://msdn.microsoft.com/en-us/library/cc313105.aspx
- [MS-OFFCRYPTO] Agile Encryption https://msdn.microsoft.com/en-us/library/dd949735(v=office.12).aspx
[MS-OFFDI] Microsoft Office File Format Documentation Introduction https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offdi/24ed256c-eb5b-494e-b4f6-fb696ad2b4dc
LibreOffice/core https://github.com/LibreOffice/core
LibreOffice/mso-dumper https://github.com/LibreOffice/mso-dumper
wvDecrypt http://www.skynet.ie/~caolan/Packages/wvDecrypt.html
Microsoft Office password protection - Wikipedia https://en.wikipedia.org/wiki/Microsoft_Office_password_protection#History_of_Microsoft_Encryption_password
office2john.py https://github.com/magnumripper/JohnTheRipper/blob/bleeding-jumbo/run/office2john.py

Alternatives

herumi/msoffice https://github.com/herumi/msoffice
DocRecrypt https://blogs.technet.microsoft.com/office_resource_kit/2013/01/23/now-you-can-reset-or-remove-a-password-from-a-word-excel-or-powerpoint-filewith-office-2013/
Apache POI - the Java API for Microsoft Documents https://poi.apache.org/

Use cases and mentions

General

https://repology.org/project/python:msoffcrypto-tool/versions (kudos to maintainers!)
https://checkroth.com/unlocking-password-protected-files.html

Malware/maldoc analysis

CTF

In other languages

In publications

Excel、データ整理＆分析、画像処理の自動化ワザを完全網羅！超速Python仕事術大全 (伊沢剛, 2022)
"Analyse de documents malveillants en 2021", MISC Hors-série N° 24, "Reverse engineering : apprenez à analyser des binaires" (Lagadec Philippe, 2021)
シゴトがはかどる Python自動処理の教科書 (クジラ飛行机, 2020)

Contributors

https://github.com/nolze/msoffcrypto-tool/graphs/contributors

Credits

The sample file for XOR Obfuscation is from: https://github.com/openwall/john-samples/tree/main/Office/Office_Secrets

	def has_record(self, target):
	pos = self.data.tell()
	while True:
	h = self.data.read(4)
	if not h:
	self.data.seek(pos)
	return False
	num, size = unpack("<HH", h)
	if num == target:
	self.data.seek(pos)
	return True
	else:
	self.data.read(size)

nolze / msoffcrypto-tool Goto Github PK

msoffcrypto-tool's Introduction

msoffcrypto-tool

Contents

Installation

Examples

As CLI tool (with password)

Decryption

Encryption (OOXML only, experimental)

As library

Decryption

Encryption (OOXML only, experimental)

Supported encryption methods

MS-OFFCRYPTO specs

Other

Tests

Todo

Resources

Alternatives

Use cases and mentions

General

Malware/maldoc analysis

CTF

In other languages

In publications

Contributors

Credits

msoffcrypto-tool's People

Contributors

Stargazers

Watchers

Forkers

msoffcrypto-tool's Issues

Recommend Projects

Recommend Topics

Recommend Org