{"id":22983200,"url":"https://github.com/nolze/msoffcrypto-tool","last_synced_at":"2025-12-15T17:44:02.773Z","repository":{"id":44884956,"uuid":"43380294","full_name":"nolze/msoffcrypto-tool","owner":"nolze","description":"Python tool and library for decrypting and encrypting MS Office files using passwords or other keys","archived":false,"fork":false,"pushed_at":"2025-01-28T04:59:17.000Z","size":846,"stargazers_count":575,"open_issues_count":10,"forks_count":89,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-04-14T00:57:05.669Z","etag":null,"topics":["command-line","decryption","doc","docx","encryption","ms-offcrypto","ole","ooxml","ppt","pptx","xls","xlsx"],"latest_commit_sha":null,"homepage":"https://msoffcrypto-tool.readthedocs.io/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nolze.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":".github/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-09-29T16:40:17.000Z","updated_at":"2025-03-26T09:01:51.000Z","dependencies_parsed_at":"2024-04-12T15:48:26.644Z","dependency_job_id":"b6948924-b2d0-4f9f-bc7d-4d309b321c7c","html_url":"https://github.com/nolze/msoffcrypto-tool","commit_stats":{"total_commits":260,"total_committers":10,"mean_commits":26.0,"dds":"0.13076923076923075","last_synced_commit":"a92117d833877255b2493afd94cf4b45052b1636"},"previous_names":[],"tags_count":39,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolze%2Fmsoffcrypto-tool","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolze%2Fmsoffcrypto-tool/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolze%2Fmsoffcrypto-tool/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nolze%2Fmsoffcrypto-tool/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nolze","download_url":"https://codeload.github.com/nolze/msoffcrypto-tool/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254169583,"owners_count":22026213,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line","decryption","doc","docx","encryption","ms-offcrypto","ole","ooxml","ppt","pptx","xls","xlsx"],"created_at":"2024-12-15T02:36:17.636Z","updated_at":"2025-12-15T17:43:57.716Z","avatar_url":"https://github.com/nolze.png","language":"Python","funding_links":[],"categories":["Python","Operating Systems"],"sub_categories":["Windows"],"readme":"# msoffcrypto-tool\n\n[![PyPI](https://img.shields.io/pypi/v/msoffcrypto-tool.svg)](https://pypi.org/project/msoffcrypto-tool/)\n[![PyPI downloads](https://img.shields.io/pypi/dm/msoffcrypto-tool.svg)](https://pypistats.org/packages/msoffcrypto-tool)\n[![build](https://github.com/nolze/msoffcrypto-tool/actions/workflows/ci.yaml/badge.svg)](https://github.com/nolze/msoffcrypto-tool/actions/workflows/ci.yaml)\n[![Coverage Status](https://codecov.io/gh/nolze/msoffcrypto-tool/branch/master/graph/badge.svg)](https://codecov.io/gh/nolze/msoffcrypto-tool)\n[![Documentation Status](https://readthedocs.org/projects/msoffcrypto-tool/badge/?version=latest)](http://msoffcrypto-tool.readthedocs.io/en/latest/?badge=latest)\n\nmsoffcrypto-tool is a Python tool and library for decrypting and encrypting MS Office files using a password or other keys.\n\n## Contents\n\n* [Installation](#installation)\n* [Examples](#examples)\n* [Supported encryption methods](#supported-encryption-methods)\n* [Tests](#tests)\n* [Todo](#todo)\n* [Resources](#resources)\n* [Use cases and mentions](#use-cases-and-mentions)\n* [Contributors](#contributors)\n* [Credits](#credits)\n\n## Installation\n\n```\npip install msoffcrypto-tool\n```\n\n## Examples\n\n### As CLI tool (with password)\n\n#### Decryption\n\nSpecify the password with `-p` flag:\n\n```\nmsoffcrypto-tool encrypted.docx decrypted.docx -p Passw0rd\n```\n\nPassword is prompted if you omit the password argument value:\n\n```bash\n$ msoffcrypto-tool encrypted.docx decrypted.docx -p\nPassword:\n```\n\nTo check if the file is encrypted or not, use `-t` flag:\n\n```\nmsoffcrypto-tool document.doc --test -v\n```\n\nIt returns `1` if the file is encrypted, `0` if not.\n\n#### Encryption (OOXML only, experimental)\n\n\u003e [!IMPORTANT]\n\u003e Encryption feature is experimental. Please use it at your own risk.\n\nTo password-protect a document, use `-e` flag along with `-p` flag:\n\n```\nmsoffcrypto-tool -e -p Passw0rd plain.docx encrypted.docx\n```\n\n### As library\n\nPassword and more key types are supported with library functions.\n\n#### Decryption\n\nBasic usage:\n\n```python\nimport msoffcrypto\n\nencrypted = open(\"encrypted.docx\", \"rb\")\nfile = msoffcrypto.OfficeFile(encrypted)\n\nfile.load_key(password=\"Passw0rd\")  # Use password\n\nwith open(\"decrypted.docx\", \"wb\") as f:\n    file.decrypt(f)\n\nencrypted.close()\n```\n\nIn-memory:\n\n```python\nimport msoffcrypto\nimport io\nimport pandas as pd\n\ndecrypted = io.BytesIO()\n\nwith open(\"encrypted.xlsx\", \"rb\") as f:\n    file = msoffcrypto.OfficeFile(f)\n    file.load_key(password=\"Passw0rd\")  # Use password\n    file.decrypt(decrypted)\n\ndf = pd.read_excel(decrypted)\nprint(df)\n```\n\nAdvanced usage:\n\n```python\n# Verify password before decryption (default: False)\n# The ECMA-376 Agile/Standard crypto system allows one to know whether the supplied password is correct before actually decrypting the file\n# Currently, the verify_password option is only meaningful for ECMA-376 Agile/Standard Encryption\nfile.load_key(password=\"Passw0rd\", verify_password=True)\n\n# Use private key\nfile.load_key(private_key=open(\"priv.pem\", \"rb\"))\n\n# Use intermediate key (secretKey)\nfile.load_key(secret_key=binascii.unhexlify(\"AE8C36E68B4BB9EA46E5544A5FDB6693875B2FDE1507CBC65C8BCF99E25C2562\"))\n\n# Check the HMAC of the data payload before decryption (default: False)\n# Currently, the verify_integrity option is only meaningful for ECMA-376 Agile Encryption\nfile.decrypt(open(\"decrypted.docx\", \"wb\"), verify_integrity=True)\n```\n\nSupported key types are\n\n- Passwords\n- Intermediate keys (optional)\n- Private keys used for generating escrow keys (escrow certificates) (optional)\n\nSee also [\"Backdooring MS Office documents with secret master keys\"](https://web.archive.org/web/20171008075059/http://secuinside.com/archive/2015/2015-1-9.pdf) for more information on the key types.\n\n#### Encryption (OOXML only, experimental)\n\n\u003e [!IMPORTANT]\n\u003e Encryption feature is experimental. Please use it at your own risk.\n\nBasic usage:\n\n```python\nfrom msoffcrypto.format.ooxml import OOXMLFile\n\nplain = open(\"plain.docx\", \"rb\")\nfile = OOXMLFile(plain)\n\nwith open(\"encrypted.docx\", \"wb\") as f:\n    file.encrypt(\"Passw0rd\", f)\n\nplain.close()\n```\n\nIn-memory:\n\n```python\nfrom msoffcrypto.format.ooxml import OOXMLFile\nimport io\n\nencrypted = io.BytesIO()\n\nwith open(\"plain.xlsx\", \"rb\") as f:\n    file = OOXMLFile(f)\n    file.encrypt(\"Passw0rd\", encrypted)\n\n# Do stuff with encrypted buffer; it contains an OLE container with an encrypted stream\n...\n```\n\n## Supported encryption methods\n\n### MS-OFFCRYPTO specs\n\n* [x] ECMA-376 (Agile Encryption/Standard Encryption)\n  * [x] MS-DOCX (OOXML) (Word 2007-)\n  * [x] MS-XLSX (OOXML) (Excel 2007-)\n  * [x] MS-PPTX (OOXML) (PowerPoint 2007-)\n* [x] Office Binary Document RC4 CryptoAPI\n  * [x] MS-DOC (Word 2002, 2003, 2004)\n  * [x] MS-XLS ([Excel 2002, 2003, 2007, 2010](https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/a3ad4e36-ab66-426c-ba91-b84433312068#Appendix_A_22)) (experimental)\n  * [x] MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental)\n* [x] Office Binary Document RC4\n  * [x] MS-DOC (Word 97, 98, 2000)\n  * [x] MS-XLS (Excel 97, 98, 2000) (experimental)\n* [ ] ECMA-376 (Extensible Encryption)\n* [x] XOR Obfuscation\n  * [x] MS-XLS ([Excel 2002, 2003](https://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-xls/a3ad4e36-ab66-426c-ba91-b84433312068#Appendix_A_21)) (experimental)\n  * [ ] MS-DOC (Word 2002, 2003, 2004?)\n\n### Other\n\n* [ ] Word 95 Encryption (Word 95 and prior)\n* [ ] Excel 95 Encryption (Excel 95 and prior)\n* [ ] PowerPoint 95 Encryption (PowerPoint 95 and prior)\n\nPRs are welcome!\n\n## Tests\n\nWith [coverage](https://github.com/nedbat/coveragepy) and [pytest](https://pytest.org/):\n\n```\npoetry install\npoetry run coverage run -m pytest -v\n```\n\n## Todo\n\n* [x] Add tests\n* [x] Support decryption with passwords\n* [x] Support older encryption schemes\n* [x] Add function-level tests\n* [x] Add API documents\n* [x] Publish to PyPI\n* [x] Add decryption tests for various file formats\n* [x] Integrate with more comprehensive projects handling MS Office files (such as [oletools](https://github.com/decalage2/oletools/)?) if possible\n* [x] Add the password prompt mode for CLI\n* [x] Improve error types (v4.12.0)\n* [ ] Add type hints\n* [ ] Introduce something like `ctypes.Structure`\n* [x] Support OOXML encryption\n* [ ] Support other encryption\n* [ ] Isolate parser\n* [ ] Redesign APIs (v6.0.0)\n\n## Resources\n\n* \"Backdooring MS Office documents with secret master keys\" [http://secuinside.com/archive/2015/2015-1-9.pdf](https://web.archive.org/web/20171008075059/http://secuinside.com/archive/2015/2015-1-9.pdf)\n* Technical Documents \u003chttps://msdn.microsoft.com/en-us/library/cc313105.aspx\u003e\n  * [MS-OFFCRYPTO] Agile Encryption \u003chttps://msdn.microsoft.com/en-us/library/dd949735(v=office.12).aspx\u003e\n* [MS-OFFDI] Microsoft Office File Format Documentation Introduction \u003chttps://learn.microsoft.com/en-us/openspecs/office_file_formats/ms-offdi/24ed256c-eb5b-494e-b4f6-fb696ad2b4dc\u003e\n* LibreOffice/core \u003chttps://github.com/LibreOffice/core\u003e\n* LibreOffice/mso-dumper \u003chttps://github.com/LibreOffice/mso-dumper\u003e\n* wvDecrypt \u003chttp://www.skynet.ie/~caolan/Packages/wvDecrypt.html\u003e\n* Microsoft Office password protection - Wikipedia \u003chttps://en.wikipedia.org/wiki/Microsoft_Office_password_protection#History_of_Microsoft_Encryption_password\u003e\n* office2john.py \u003chttps://github.com/magnumripper/JohnTheRipper/blob/bleeding-jumbo/run/office2john.py\u003e\n\n## Alternatives\n\n* herumi/msoffice \u003chttps://github.com/herumi/msoffice\u003e\n* DocRecrypt \u003chttps://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/\u003e\n* Apache POI - the Java API for Microsoft Documents \u003chttps://poi.apache.org/\u003e\n\n## Use cases and mentions\n\n### General\n\n* \u003chttps://repology.org/project/python:msoffcrypto-tool/versions\u003e (kudos to maintainers!)\n\u003c!-- * \u003chttps://checkroth.com/unlocking-password-protected-files.html\u003e (outdated) --\u003e\n\n### Corporate\n\n* Workato \u003chttps://docs.workato.com/connectors/python.html#supported-features\u003e \u003c!-- https://web.archive.org/web/20240525062245/https://docs.workato.com/connectors/python.html#supported-features --\u003e\n* Check Point \u003chttps://www.checkpoint.com/about-us/copyright-and-trademarks/\u003e \u003c!-- https://web.archive.org/web/20230326071230/https://www.checkpoint.com/about-us/copyright-and-trademarks/ --\u003e\n\n### Malware/maldoc analysis\n\n* \u003chttps://github.com/jbremer/sflock/commit/3f6a96abe1dbb4405e4fb7fd0d16863f634b09fb\u003e\n* \u003chttps://isc.sans.edu/forums/diary/Video+Analyzing+Encrypted+Malicious+Office+Documents/24572/\u003e\n\n### CTF\n\n* \u003chttps://github.com/shombo/cyberstakes-writeps-2018/tree/master/word_up\u003e\n* \u003chttps://github.com/willi123yao/Cyberthon2020_Writeups/blob/master/csit/Lost_Magic\u003e\n\n### In other languages\n\n* \u003chttps://github.com/dtjohnson/xlsx-populate\u003e\n* \u003chttps://github.com/opendocument-app/OpenDocument.core/blob/233663b039/src/internal/ooxml/ooxml_crypto.h\u003e\n* \u003chttps://github.com/jaydadhania08/PHPDecryptXLSXWithPassword\u003e\n* \u003chttps://github.com/epicentre-msf/rpxl\u003e\n\n### In publications\n\n* [Excel、データ整理＆分析、画像処理の自動化ワザを完全網羅！ 超速Python仕事術大全](https://books.google.co.jp/books?id=TBdVEAAAQBAJ\u0026q=msoffcrypto) (伊沢剛, 2022)\n* [\"Analyse de documents malveillants en 2021\"](https://twitter.com/decalage2/status/1435255507846053889), MISC Hors-série N° 24, \"Reverse engineering : apprenez à analyser des binaires\" (Lagadec Philippe, 2021)\n* [シゴトがはかどる Python自動処理の教科書](https://books.google.co.jp/books?id=XEYUEAAAQBAJ\u0026q=msoffcrypto) (クジラ飛行机, 2020)\n\n## Contributors\n\n* \u003chttps://github.com/nolze/msoffcrypto-tool/graphs/contributors\u003e\n\n## Credits\n\n* The sample file for XOR Obfuscation is from: \u003chttps://github.com/openwall/john-samples/tree/main/Office/Office_Secrets\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolze%2Fmsoffcrypto-tool","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnolze%2Fmsoffcrypto-tool","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnolze%2Fmsoffcrypto-tool/lists"}