https://github.com/maxirmx/design
Delphi CADES signing
https://github.com/maxirmx/design
cades cryptoprocsp delphi digitalsignature
Last synced: 5 months ago
JSON representation
Delphi CADES signing
- Host: GitHub
- URL: https://github.com/maxirmx/design
- Owner: maxirmx
- License: mit
- Created: 2024-11-06T16:47:26.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-11-25T20:10:26.000Z (over 1 year ago)
- Last Synced: 2025-06-29T14:39:33.923Z (12 months ago)
- Topics: cades, cryptoprocsp, delphi, digitalsignature
- Language: Pascal
- Homepage:
- Size: 421 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
= Модуль `CadesSigner`
Модуль `CadesSigner` предоставляет функции для интеграции поддержки Электронной Цифровой Подписи ("ЭЦП") с использованием алгоритмов, установленных ГОСТ Р 34.10/11/12.
== Содержание
* <<Состав репозитория>>
* <<Установка>>
* <<Публичное API>>
* <<Примеры использования>>
* <<Ошибки>>
== Состав репозитория
* Каталог `CadesSigner`: модуль `CadesSigner` и зависимости. Каталог включает в себя несколько несколько необходимых файлов из библиотеки link:https://sourceforge.net/projects/jedi-apilib/[Jedi jwa]. Этти файлы имеют префикс `Jedi` и они не требуются, если Jedi установлена в полном объёме.
* Каталог `SampleApp`: демонстрационное\тестовое приложение.
* Каталог `Tools`: вспомогательные артефакты разработки, не представлют интереса при интеграции модуля.
== Установка
Модуль разрабатывался и тестировался с исполльзованием link:https://cryptopro.ru/products/csp[CryptoPro CSP].
Соответственно, для сборки и использования модуля CadesSign необходимо установить link:https://cryptopro.ru/products/cades/sdk[КриптоПро ЭЦП SDK]
Новые версии CryptoPro CSP устанавливают свои библиотеки в link:https://docs.cryptopro.ru/cades/usage/cades-manifests?id=%d0%97%d0%b0%d0%b3%d1%80%d1%83%d0%b7%d0%ba%d0%b0-cadesdllxadesdll-%d0%b2-%d0%bf%d1%80%d0%b8%d0%bb%d0%be%d0%b6%d0%b5%d0%bd%d0%b8%d0%b5-%d0%bf%d0%be%d0%bb%d1%8c%d0%b7%d0%be%d0%b2%d0%b0%d1%82%d0%b5%d0%bb%d1%8f-%d1%82%d0%be%d0%bb%d1%8c%d0%ba%d0%be-%d0%b4%d0%bb%d1%8f-windows[режиме изоляции], который не поддержаивается старыми средами разработки, такими как Delphi7 (кажется это так???).
Для работы приложений, разработанных на Delphi7, необходим установка "side-by-side". Говоря по простому, после установки SDK нужно найти библиотеку `cades.dll` и скопировать её в каталог, где будет размещено разрабатываемое приложение.
== Публичное API
=== Типы
* `T20Bytes`: Массив из 20 байтов, предназначенный для хранения SHA-1 хеш-суммы (отпечатка) сертификата.
* `TCertOption`: Запись, представляющая параметры сертификата.
** `FriendlyName` - "человеческое" имя сертификатв. Обычно ФИО, но не обязательно. Может быть разным на разных компьютерах, может меняться пользователем
** `Thumbprint` - уникальный идентификатор ("отпечаток") сертификата всегда одинаковый, в том числе на разных компьютерах.
** `ThumbprintStr` - читаемое представление "отпечатка" в виде строки шестнадцатиричных символов
** `StartDateTime` - дата/время начала действия сертификата
** `EndDateTime` - дата/время окончания действия сертификата
=== Исключения
* `ECadesSignerException`: Исключение, используемое для обработки ошибок при работе с сертификатами и криптографическими операциями.
** `ErrorCode` - код ошибки из Windows API, который указывает на причину сбоя.
=== Функции
==== `GetCertificates`
[source,delphi]
----
function GetCertificates(const Prefix: string): TList;
----
Возвращает список сертификатов, доступных в системе, на основе указанного префикса идентификатора криптографического алгоритма ("OID").
Вероятно, префикс всегда будет '1.2.643', где
1: код стандартов International Organization for Standardization(ИСО).
2: означает, что стандарт разработан организацией членом ИСО
643: код страны - Россия
* *Параметры*:
** `Prefix`: Строка, которая используется для фильтрации сертификатов по OID.
* *Результат*:
** Возвращает список сертификатов в виде `TList`, содержащий объекты `TCertOption`.
==== `InitializeCades`
[source,delphi]
----
procedure InitializeCades;
----
Загружает ```cades.dll```. Эта библиотека нужна при вызове ```SignFile/SignFileStr``` и она грузится динамически с помощью ```LoadLibrary```. См. выше соображения относительно установки.
==== `FinalizeCades`
[source,delphi]
----
procedure FinalizeCades;
----
Выгружает cades.dll
==== `SignFile`
[source,delphi]
----
procedure SignFile(const FilePath: string; const SigPath: string; const Thumbprint: T20Bytes; const Password: string);
----
Создает ЭЦП для файла, используя указанный сертификат.
* *Параметры*:
** `FilePath`: Полный путь к файлу, который нужно подписать.
** `SigPath`: Полный путь к файлу, куда нужно поместить ЭЦП.
** `Thumbprint`: Отпечаток (thumbprint) сертификата в формате `T20Bytes`, который будет использоваться для подписи.
** `Password`: Пароль для доступа к сертификату.
==== `SignFileStr`
[source,delphi]
----
procedure SignFileStr(const FilePath: string; const SigPath: string; const ThumbprintStr: string; const Password: string);
----
Создает цифровую подпись для файла, используя указанный сертификат.
* *Параметры*:
** `FilePath`: Полный путь к файлу, который нужно подписать.
** `SigPath`: Полный путь к файлу, куда нужно поместить ЭЦП.
** `ThumbprintStr`: Читаемое представление отпечатка (thumbprint) сертификата в виде строки шестнадцатиричных символов.
** `Password`: Пароль для доступа к сертификату.
=== Примеры использования
Пример использования публичного API находится в файде DeSign.dpr
=== Ошибки
При возникновении ошибок во время операций с сертификатами и файлами модуль `CadesSigner` генерирует исключения типа `ECadesSignerException`, которые содержат сообщение об ошибке и код ошибки. Например, ошибка `ERR_OPEN_STORE_FAILED` указывает на невозможность открытия хранилища сертификатов.
=== Проверка подписи
Сформированную подпись можно проверить с помощью link:https://dss.cryptopro.ru/verify/[тестовой службы проверки подписи и сертификатов «КриптоПро SVS»].
---
Этот README описывает только публичный интерфейс модуля. Подробная документация по внутренним методам, используемым для обработки файлов и криптографических операций, доступна в исходном коде.