Metadata-Version: 2.4
Name: pycdoc
Version: 0.1.0
Summary: Python bindings for libcdoc - read and write encrypted CDOC containers
Keywords: cdoc,encryption,decryption,container,estonia,id-card,cdoc2
Author-Email: =?utf-8?q?Madis_V=C3=A4in?= <madisvain@gmail.com>
License-Expression: LGPL-2.1-or-later
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Security :: Cryptography
Project-URL: Homepage, https://github.com/namespace-ee/pycdoc
Project-URL: Documentation, https://github.com/namespace-ee/pycdoc
Project-URL: Repository, https://github.com/namespace-ee/pycdoc
Project-URL: Changelog, https://github.com/namespace-ee/pycdoc/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/namespace-ee/pycdoc/issues
Requires-Python: >=3.9
Provides-Extra: ldap
Requires-Dist: ldap3>=2.9; extra == "ldap"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Description-Content-Type: text/markdown

# pycdoc

Python bindings for [libcdoc](https://github.com/open-eid/libcdoc) - a library for reading and writing encrypted CDOC containers.

CDOC is a file format for encrypting documents, used primarily in Estonia for secure document exchange with the Estonian ID-card ecosystem.

## Installation

```bash
pip install pycdoc
```

## Requirements

### Runtime
- Python 3.9+
- OpenSSL 3.0+ (usually pre-installed on modern systems)

### Building from Source

Building from source requires:
- Python 3.9+
- CMake 3.18+
- SWIG 4.0+
- OpenSSL 3.0+
- libxml2
- zlib
- FlatBuffers
- C++23 compatible compiler

**macOS:**
```bash
brew install cmake swig openssl@3 libxml2 flatbuffers
```

**Ubuntu/Debian:**
```bash
sudo apt install cmake swig libssl-dev libxml2-dev zlib1g-dev libflatbuffers-dev
```

**Fedora/RHEL:**
```bash
sudo dnf install cmake swig openssl-devel libxml2-devel zlib-devel flatbuffers-devel
```

## Quick Start

Install with LDAP support for certificate lookup:

```bash
pip install pycdoc[ldap]
```

### Encrypting Files

```python
import pycdoc

# Encrypt a file for an Estonian ID card holder
pycdoc.encrypt("document.pdf", "38607080247", output="encrypted.cdoc")

# Get CDOC as bytes instead of writing to file
cdoc_bytes = pycdoc.encrypt("document.pdf", "38607080247")

# Encrypt raw bytes
pycdoc.encrypt(b"secret content", "38607080247", filename="secret.txt", output="encrypted.cdoc")

# Encrypt multiple files into one container
pycdoc.encrypt(["file1.pdf", "file2.docx"], "38607080247", output="bundle.cdoc")
```

The recipient can decrypt with [DigiDoc4 Client](https://www.id.ee/en/article/install-id-software/) or `cdoc-tool`.

## API Overview

### Core Classes

- `CDocReader` - Read and decrypt CDOC containers
- `CDocWriter` - Create and encrypt CDOC containers

### Configuration

- `Configuration` - Base configuration class (can be subclassed)
- `JSONConfiguration` - JSON file-based configuration

### Backends

- `CryptoBackend` - Cryptographic operations backend (can be subclassed)
- `NetworkBackend` - Network operations backend for key servers
- `PKCS11Backend` - PKCS#11 hardware token backend (smart cards, HSMs)

### Data Types

- `Recipient` - Encryption recipient information
- `Lock` - Decryption lock information
- `FileInfo` - File metadata (name, size)
- `DataSource` - Abstract data source for streaming
- `DataConsumer` - Abstract data consumer for streaming

### Result Codes

- `OK` - Operation successful
- `WRONG_KEY` - Incorrect decryption key
- `DATA_FORMAT_ERROR` - Invalid container format
- `CRYPTO_ERROR` - Cryptographic operation failed
- `PKCS11_ERROR` - PKCS#11/smart card error

Use `pycdoc.get_error_str(code)` to get human-readable error descriptions.

## Building from Source

1. Clone the repository:
```bash
git clone https://github.com/namespace-ee/pycdoc.git
cd pycdoc
```

2. Clone libcdoc:
```bash
git clone https://github.com/open-eid/libcdoc.git
```

3. Build the wheel:
```bash
pip install build
python -m build --wheel
```

4. Install the wheel:
```bash
pip install dist/pycdoc-*.whl
```

## Development

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate

# Install build dependencies
pip install build scikit-build-core swig

# Build wheel
python -m build --wheel

# Install in development mode (rebuild required after changes)
pip install dist/pycdoc-*.whl --force-reinstall
```

## License

This library is licensed under the GNU Lesser General Public License v2.1 or later (LGPL-2.1-or-later).

See [LICENSE](LICENSE) for the full license text.

## Links

- [libcdoc repository](https://github.com/open-eid/libcdoc)
- [Estonian ID software](https://www.id.ee/)
- [CDOC 2.0 specification](https://github.com/open-eid/cdoc2-spec)
