• Home
  • History
  • Annotate
Name Date Size #Lines LOC

..03-May-2022-

msoffcrypto/H03-Sep-2020-2,7232,118

msoffcrypto_tool.egg-info/H03-May-2022-198145

tests/H03-Sep-2020-187116

.nosercH A D03-Sep-202082 75

MANIFEST.inH A D03-Sep-2020186 108

PKG-INFOH A D03-Sep-20208.1 KiB198145

README.mdH A D03-Sep-20206.3 KiB187135

setup.cfgH A D03-Sep-202038 53

setup.pyH A D03-Sep-20201.4 KiB5347

README.md

1# msoffcrypto-tool
2
3[![PyPI version](https://badge.fury.io/py/msoffcrypto-tool.svg)](https://badge.fury.io/py/msoffcrypto-tool)
4[![PyPI downloads](https://img.shields.io/pypi/dm/msoffcrypto-tool.svg)](https://pypistats.org/packages/msoffcrypto-tool)
5[![Build Status](https://travis-ci.com/nolze/msoffcrypto-tool.svg?branch=master)](https://travis-ci.com/nolze/msoffcrypto-tool)
6[![Coverage Status](https://codecov.io/gh/nolze/msoffcrypto-tool/branch/master/graph/badge.svg)](https://codecov.io/gh/nolze/msoffcrypto-tool)
7[![Documentation Status](https://readthedocs.org/projects/msoffcrypto-tool/badge/?version=latest)](http://msoffcrypto-tool.readthedocs.io/en/latest/?badge=latest)
8
9msoffcrypto-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.
10
11## Contents
12
13* [Install](#install)
14* [Examples](#examples)
15* [Supported encryption methods](#supported-encryption-methods)
16* [Tests](#tests)
17* [Todo](#todo)
18* [Resources](#resources)
19* [Use cases and mentions](#use-cases-and-mentions)
20* [Contributors](#contributors)
21
22## Install
23
24```
25pip install msoffcrypto-tool
26```
27
28## Examples
29
30### As CLI tool (with password)
31
32```
33msoffcrypto-tool encrypted.docx decrypted.docx -p Passw0rd
34```
35
36Password is prompted if you omit the password argument value:
37
38```bash
39$ msoffcrypto-tool encrypted.docx decrypted.docx -p
40Password:
41```
42
43Test if the file is encrypted or not (exit code 0 or 1 is returned):
44
45```
46msoffcrypto-tool document.doc --test -v
47```
48
49### As library
50
51Password and more key types are supported with library functions.
52
53Basic usage:
54
55```python
56import msoffcrypto
57
58file = msoffcrypto.OfficeFile(open("encrypted.docx", "rb"))
59
60# Use password
61file.load_key(password="Passw0rd")
62
63file.decrypt(open("decrypted.docx", "wb"))
64```
65
66Basic usage (in-memory):
67
68```python
69import msoffcrypto
70import io
71import pandas as pd
72
73file = msoffcrypto.OfficeFile(open("encrypted.xlsx", "rb"))
74
75# Use password
76file.load_key(password="Passw0rd")
77
78decrypted = io.BytesIO()
79file.decrypt(decrypted)
80
81df = pd.read_excel(decrypted)
82print(df)
83```
84
85Advanced usage:
86
87```python
88# Verify password before decryption (default: False)
89# The ECMA-376 Agile/Standard crypto system allows one to know whether the supplied password is correct before actually decrypting the file
90# Currently, the verify_password option is only meaningful for ECMA-376 Agile/Standard Encryption
91file.load_key(password="Passw0rd", verify_password=True)
92
93# Use private key
94file.load_key(private_key=open("priv.pem", "rb"))
95
96# Use intermediate key (secretKey)
97file.load_key(secret_key=binascii.unhexlify("AE8C36E68B4BB9EA46E5544A5FDB6693875B2FDE1507CBC65C8BCF99E25C2562"))
98
99# Check the HMAC of the data payload before decryption (default: False)
100# Currently, the verify_integrity option is only meaningful for ECMA-376 Agile Encryption
101file.decrypt(open("decrypted.docx", "wb"), verify_integrity=True)
102```
103
104## Supported encryption methods
105
106### MS-OFFCRYPTO specs
107
108* [x] ECMA-376 (Agile Encryption/Standard Encryption)
109  * [x] MS-DOCX (OOXML) (Word 2007-2016)
110  * [x] MS-XLSX (OOXML) (Excel 2007-2016)
111  * [x] MS-PPTX (OOXML) (PowerPoint 2007-2016)
112* [x] Office Binary Document RC4 CryptoAPI
113  * [x] MS-DOC (Word 2002, 2003, 2004)
114  * [x] MS-XLS (Excel 2002, 2003, 2004) (experimental)
115  * [x] MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental)
116* [x] Office Binary Document RC4
117  * [x] MS-DOC (Word 97, 98, 2000)
118  * [x] MS-XLS (Excel 97, 98, 2000) (experimental)
119* [ ] ECMA-376 (Extensible Encryption)
120* [ ] XOR Obfuscation
121
122### Other
123
124* [ ] Word 95 Encryption (Word 95 and prior)
125* [ ] Excel 95 Encryption (Excel 95 and prior)
126* [ ] PowerPoint 95 Encryption (PowerPoint 95 and prior)
127
128PRs are welcome!
129
130## Tests
131
132Tests can be run in various ways:
133
134* `python -m nose -c .noserc`
135* `nosetests -c .noserc`
136* `python -m unittest discover`
137* `python setup.py test`
138* `./tests/test_cli.sh`
139
140If the [cryptography](https://pypi.org/project/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.
141
142## Todo
143
144* [x] Add tests
145* [x] Support decryption with passwords
146* [x] Support older encryption schemes
147* [x] Add function-level tests
148* [x] Add API documents
149* [x] Publish to PyPI
150* [x] Add decryption tests for various file formats
151* [x] Integrate with more comprehensive projects handling MS Office files (such as [oletools](https://github.com/decalage2/oletools/)?) if possible
152* [x] Add the password prompt mode for CLI
153* [ ] Redesign APIs (v5.0.0)
154* [ ] Improve error types (v5.0.0)
155* [ ] Use a kind of `ctypes.Structure`
156* [ ] Support encryption
157
158## Resources
159
160* "Backdooring MS Office documents with secret master keys" <http://secuinside.com/archive/2015/2015-1-9.pdf>
161* Technical Documents <https://msdn.microsoft.com/en-us/library/cc313105.aspx>
162  * [MS-OFFCRYPTO] Agile Encryption <https://msdn.microsoft.com/en-us/library/dd949735(v=office.12).aspx>
163* LibreOffice/core <https://github.com/LibreOffice/core>
164* LibreOffice/mso-dumper <https://github.com/LibreOffice/mso-dumper>
165* wvDecrypt <http://www.skynet.ie/~caolan/Packages/wvDecrypt.html>
166* Microsoft Office password protection - Wikipedia <https://en.wikipedia.org/wiki/Microsoft_Office_password_protection#History_of_Microsoft_Encryption_password>
167* office2john.py <https://github.com/magnumripper/JohnTheRipper/blob/bleeding-jumbo/run/office2john.py>
168
169## Alternatives
170
171* herumi/msoffice <https://github.com/herumi/msoffice>
172* 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/>
173* Apache POI - the Java API for Microsoft Documents <https://poi.apache.org/>
174
175## Use cases and mentions
176
177* <https://repology.org/project/python:msoffcrypto-tool/versions> (kudos to maintainers!)
178* <https://github.com/jbremer/sflock/commit/3f6a96abe1dbb4405e4fb7fd0d16863f634b09fb>
179* <https://github.com/dtjohnson/xlsx-populate>
180* <https://github.com/shombo/cyberstakes-writeps-2018/tree/master/word_up>
181* <https://isc.sans.edu/forums/diary/Video+Analyzing+Encrypted+Malicious+Office+Documents/24572/>
182* <https://checkroth.com/unlocking-password-protected-files.html>
183
184## Contributors
185
186* <https://github.com/nolze/msoffcrypto-tool/graphs/contributors>
187