pycdoc

Python bindings for 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

uv add pycdoc

Requirements

Runtime

• Python 3.10+
• OpenSSL 3.5+ (usually pre-installed on modern systems)

Building from Source

Building from source requires:

• Python 3.10+
• CMake 3.20+
• SWIG 4.0+
• OpenSSL 3.5+
• libxml2
• zlib
• FlatBuffers
• C++23 compatible compiler

macOS:

brew install cmake swig openssl@3 libxml2 flatbuffers

Ubuntu/Debian:

sudo apt install cmake swig libssl-dev libxml2-dev zlib1g-dev libflatbuffers-dev

Fedora/RHEL:

sudo dnf install cmake swig openssl-devel libxml2-devel zlib-devel flatbuffers-devel

Quick Start

Install with LDAP support for certificate lookup:

uv add "pycdoc[ldap]"

Encrypting Files

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 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 with submodules:

git clone --recurse-submodules https://github.com/namespace-ee/pycdoc.git
cd pycdoc

2. Build the wheel:

uv build --wheel

3. Install the wheel:

uv pip install dist/pycdoc-*.whl

Development

# Build wheel
uv build --wheel

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

# Run tests
uv run pytest tests/ -v

License

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

See LICENSE for the full license text.

Links

• libcdoc repository
• Estonian ID software
• CDOC 2.0 specification