# msoffcrypto-tool

> Python tool and library for decrypting and encrypting MS Office files using a password or other keys

- **URL**: https://www.freshcrate.ai/projects/msoffcrypto-tool
- **Author**: nolze
- **Category**: Frameworks
- **Latest version**: `6.0.0` (2026-04-21)
- **License**: MIT
- **Source**: https://github.com/nolze/msoffcrypto-tool
- **Language**: Python
- **GitHub**: 614 stars, 91 forks
- **Registry**: pypi (`msoffcrypto-tool`)
- **Tags**: `pypi`

## Description

# msoffcrypto-tool

[![PyPI](https://img.shields.io/pypi/v/msoffcrypto-tool.svg)](https://pypi.org/project/msoffcrypto-tool/)
[![PyPI downloads](https://img.shields.io/pypi/dm/msoffcrypto-tool.svg)](https://pypistats.org/packages/msoffcrypto-tool)
[![build](https://github.com/nolze/msoffcrypto-tool/actions/workflows/ci.yaml/badge.svg)](https://github.com/nolze/msoffcrypto-tool/actions/workflows/ci.yaml)
[![Coverage Status](https://codecov.io/gh/nolze/msoffcrypto-tool/branch/master/graph/badge.svg)](https://codecov.io/gh/nolze/msoffcrypto-tool)
[![Documentation Status](https://readthedocs.org/projects/msoffcrypto-tool/badge/?version=latest)](http://msoffcrypto-tool.readthedocs.io/en/latest/?badge=latest)

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

## Contents

* [Installation](#installation)
* [Examples](#examples)
* [Supported encryption methods](#supported-encryption-methods)
* [Tests](#tests)
* [Todo](#todo)
* [Resources](#resources)
* [Use cases and mentions](#use-cases-and-mentions)
* [Contributors](#contributors)
* [Credits](#credits)

## 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:

```bash
$ 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:

```python
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:

```python
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:

```python
# 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"](https://web.archive.org/web/20171008075059/http://secuinside.com/archive/2015/2015-1-9.pdf) 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:

```python
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:

```python
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

* [x] ECMA-376 (Agile Encryption/Standard Encryption)
  * [x] MS-DOCX (OOXML) (Word 2007-)
  * [x] MS-XLSX (OOXML) (Excel 2007-)
  * [x] MS-PPTX (OOXML) (PowerPoint 2007-)
* [x] Office Binary Document RC4 CryptoAPI
  * [x] MS-DOC (Word 2002, 2003, 2004)
  * [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)
  * [x] MS-PPT (PowerPoint 2002, 2003, 2004) (partial, experimental)
* [x]

## Recent releases

| Version | Date | Urgency | Changes |
| --- | --- | --- | --- |
| `6.0.0` | 2026-04-21 | Low | Imported from PyPI (6.0.0) |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |
| `master@2026-01-12` | 2026-01-12 | Low | Latest activity on master branch |

## Citation

- HTML: https://www.freshcrate.ai/projects/msoffcrypto-tool
- Markdown: https://www.freshcrate.ai/projects/msoffcrypto-tool.md
- Dependencies JSON: https://www.freshcrate.ai/api/projects/msoffcrypto-tool/deps

_Generated by freshcrate.ai. Indexes pypi releases for AI-agent ecosystem packages._