Metadata-Version: 2.5
Name: django-pdf-sign
Version: 1.0.0
Summary: Client-side electronic signatures for PDF documents in Django: GOST 34.10-2012 (qualified signatures) and PAdES (RSA/ECDSA).
Project-URL: Homepage, https://github.com/selimoves/django_pdf_sign
Project-URL: Documentation, https://github.com/selimoves/django_pdf_sign#readme
Project-URL: Issues, https://github.com/selimoves/django_pdf_sign/issues
Project-URL: Source, https://github.com/selimoves/django_pdf_sign
Author-email: "Eldar S. Selimov" <selimoves@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cades,django,electronic-signature,gost,gost-34.10-2012,pades,pdf,qualified-signature,signature
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Framework :: Django :: 6.1
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: asn1crypto<2,>=1.5.1
Requires-Dist: cryptography<51,>=48
Requires-Dist: django<6.2,>=5.2
Requires-Dist: gostcrypto<2,>=1.2.5
Requires-Dist: pyhanko[opentype]<0.39,>=0.38
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: cyclonedx-bom>=6.0; extra == 'dev'
Requires-Dist: django-stubs>=5.0; extra == 'dev'
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pre-commit>=3.8; extra == 'dev'
Requires-Dist: psycopg[binary]>=3.2; extra == 'dev'
Requires-Dist: pytest-benchmark>=5.1; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-django>=4.9; extra == 'dev'
Requires-Dist: pytest-randomly>=3.15; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: ruff>=0.9; extra == 'dev'
Requires-Dist: twine>=5.1; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.26; extra == 'docs'
Provides-Extra: qr
Requires-Dist: pyhanko[qr]<0.39,>=0.38; extra == 'qr'
Description-Content-Type: text/markdown

# django-pdf-sign

Клиентские электронные подписи PDF-документов в Django.

Сервер никогда не хранит закрытые ключи. Он подготавливает PDF с видимым
штампом, передаёт браузеру точные байты для подписи (плагин КриптоПро),
проверяет присланную отсоединённую CMS и встраивает её в документ.

- **ГОСТ Р 34.10-2012 / CAdES-BES** — квалифицированные подписи
  (Стрибог-256/512), проверяемые российскими валидаторами при наличии
  квалифицированного сертификата.
- **PAdES / RSA-ECDSA** — подписи, совместимые с Adobe.

## Установка

```bash
pip install django-pdf-sign
```

Серверу не нужен КриптоПро: проверка выполняется библиотеками `gostcrypto`
и `cryptography`.

## Быстрый старт

```python
# settings.py
INSTALLED_APPS = [
    # ...
    "django.contrib.contenttypes",
    "django_pdf_sign",
]
```

```python
from django_pdf_sign.services import prepare_signing, complete_signing

# Шаг 1: браузер присылает сертификат, сервер готовит документ.
prepared = prepare_signing(
    document=invoice,
    user=request.user,
    certificate_der=certificate_der,  # DER-сертификат из браузера
    page=-1,                           # последняя страница
    box=(57, 57, 284, 170),            # 80x40 мм, отступы 20 мм
)

# Шаг 2: отдать браузеру.
response = {
    "session_id": str(prepared.session.pk),
    "bytes_to_sign": base64.b64encode(prepared.bytes_to_sign).decode(),
    "digest_algorithm": prepared.digest_algorithm,
    "expires_at": prepared.expires_at.isoformat(),
}

# Шаг 3: браузер вернул отсоединённую CMS — проверить и встроить.
result = complete_signing(
    session_id=prepared.session.pk,
    cms=cms_bytes,
    user=request.user,
)
result.signed_pdf      # байты подписанного PDF
result.record          # неизменяемая запись аудита
```

## Что делает пакет

- Добавляет поле подписи и штамп в российском стиле.
- Возвращает точные байты `/ByteRange` для подписи.
- Проверяет, что CMS покрывает именно эти байты, сертификат совпадает с
  сессией, а подпись криптографически верна.
- Встраивает CMS, сохраняет подписанный PDF и пишет запись аудита.
- Проверяет цепочку сертификатов, отзыв (CRL и OCSP) и метки времени
  CAdES-T, если задана политика.
- Помечает и удаляет брошенные сессии (`python manage.py pdf_sign_cleanup`).

## Чего пакет не делает

- Не хранит, не принимает и не журналирует закрытые ключи, PIN и контейнеры.
- Не является удостоверяющим центром и не выдаёт сертификаты.
- Не заменяет сертифицированное СКЗИ на стороне подписанта.
- Не даёт юридическую силу сам по себе: нужны квалифицированный сертификат и
  сертифицированное СКЗИ. Подробности в [docs/legal.md](docs/legal.md).

## Настройки

```python
DJANGO_PDF_SIGN = {
    "SESSION_TTL": 900,
    "BYTES_RESERVED": 16384,
    "MAX_DOCUMENT_BYTES": 25 * 1024 * 1024,
    "DEFAULT_PAGE": -1,
    "DEFAULT_BOX": (57, 57, 284, 170),
    "SUBFILTER": None,
    "STAMP": {
        "TEXT": "...",
        "FONT_PATH": None,
        "FONT_SIZE": 7,
        "BORDER_WIDTH": 1,
        "BACKGROUND_PATH": None,
    },
    "VERIFY": {
        "CHECK_CHAIN": False,
        "TRUST_ROOTS": (),
        "INTERMEDIATE_CERTS": (),
        "CRLS": (),
        "OCSPS": (),
        "REVOCATION_MODE": "soft-fail",  # none | soft-fail | require
        "ALLOW_FETCHING": False,
        "FETCH_ALLOWED_HOSTS": (),
        "CHECK_TIMESTAMPS": False,
        "REQUIRE_TIMESTAMP": False,
    },
    "PREPARED_UPLOAD_TO": "django_pdf_sign/prepared/%Y/%m/%d",
    "SIGNED_UPLOAD_TO": "django_pdf_sign/signed/%Y/%m/%d",
    "ON_EVENT": None,
}
```

Пути к корневым сертификатам, CRL и ответам OCSP — строки, файлы читаются при
создании политики.

## Документация

- [Сайт документации](https://selimoves.github.io/django_pdf_sign/) — быстрый старт, справочник настроек, cookbook.
- [API](docs/api.md) — стабильный публичный контракт.
- [Протокол](docs/protocol.md) — контракт сервер/клиент и пример на JS.
- [Штамп](docs/stamp.md) — шаблон, размещение, настройка.
- [Юридическая сила](docs/legal.md) — что делает подпись действительной.
- [Ограничения](docs/limits.md) — производительность и лимиты.
- [Эксплуатация](docs/operations.md) — хранилище, ретенция, мониторинг.
- [Фикстуры](docs/fixtures.md) — происхождение тестовых сертификатов.
- [Интероп с КриптоПро](docker/cryptopro/README.md) — проверка на реальном CSP.
- [CHANGELOG](CHANGELOG.md), [политика безопасности](SECURITY.md), [поддержка](SUPPORT.md).
- [Как внести вклад](CONTRIBUTING.md), [дорожная карта](ROADMAP.md).

## Требования

- Python 3.11+
- Django 5.2 LTS, 6.0 или 6.1 (Django 4.2 не поддерживается)
- `pyhanko[opentype]`, `asn1crypto`, `cryptography`, `gostcrypto`

## Разработка

```bash
uv sync --all-extras
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run python -m mypy
uv build
```

## Лицензия

MIT. Встроенный шрифт DejaVu Sans распространяется по лицензии Bitstream Vera;
см. `src/django_pdf_sign/fonts/LICENSE.DejaVu`.
