@innovations28/e-sign

Бібліотека електронного підпису для Angular на основі бібліотеки підпису користувача ЦСК від АТ «ІІТ».

Встановлення

npm i @innovations28/e-sign

Бібліотека підпису ІІТ (euscp) постачається разом з пакетом і встановлюється автоматично — окремих дій не потрібно.

Під час збірки застосунку Angular може вивести попередження про CommonJS-залежність:

Module 'euscp' used by '.../innovations28-e-sign.mjs' is not ESM

Це попередження, а не помилка. Щоб його прибрати, додайте до angular.json у architect.build.options свого застосунку:

"allowedCommonJsDependencies": ["euscp"]

Підключення

import { ESignModule, SignAlgo } from '@innovations28/e-sign';

@NgModule({
  imports: [
    ESignModule.forRoot({
      proxyServerUrl: 'https://your-proxy/ProxyHandler.php',
      caPath: 'assets/CAs.json',
      caCertificatesPath: 'assets/CACertificates.p7b',
      maxDataSizeMb: 50,
    }),
  ],
})
export class AppModule {}

Параметри

| Параметр | Призначення | |---|---| | proxyServerUrl | Адреса proxy-сервісу, через який ідуть запити до серверів ЦСК (CMP, OCSP, TSP) | | caPath | Перелік ЦСК. Може вказувати на власний бекенд, тоді перелік оновлюється без релізу застосунку | | caCertificatesPath | Сертифікати ЦСК (.p7b), там само | | maxDataSizeMb | Максимальний розмір даних для підпису, МБ | | signAlgo | Алгоритм підпису. За замовчуванням Unknown — визначається за сертифікатом ключа | | allowedKeyMediaTypes | Типи носіїв для апаратного підпису. Якщо не задано — усі, які знає агент, включно з псевдоносієм «файлова система» | | initTimeoutMs | Скільки чекати на ініціалізацію бібліотеки, мс. За замовчуванням 60000 | | debug | Логування етапів у консоль |

Алгоритм підпису

За замовчуванням алгоритм не задається (SignAlgo.Unknown) — бібліотека обирає його за сертифікатом зчитаного ключа: якщо ЦСК підписав сертифікат за ГОСТ 34.311, підпис буде за ГОСТ 34.311, якщо за ДСТУ 7564 — за ДСТУ 7564. Алгоритм гешування визначається разом з ним.

Це означає, що перехід на ДСТУ 7564 не потребує змін у застосунку: ключі з новими сертифікатами починають підписуватись новим алгоритмом самі, а ключі зі старими сертифікатами продовжують працювати як раніше.

Задавати алгоритм явно варто лише тоді, коли його диктує приймаюча сторона:

ESignModule.forRoot({ signAlgo: SignAlgo.DSTU4145WithDSTU7564 })

Змінити під час роботи (наприклад, за прапорцем, який віддає сервер):

this.http.get('/api/crypto/hashAlgo', { responseType: 'text' })
  .subscribe((algo) => euSign.setSignAlgo(
    algo === 'DSTU7564'
      ? SignAlgo.DSTU4145WithDSTU7564
      : SignAlgo.DSTU4145WithGOST34311));

Перевірка підпису від налаштування не залежить: алгоритм визначається з самого підпису, тому verifyData і getSigners працюють з будь-яким.

Увага при оновленні з версій до 0.0.37. Стара реалізація завжди підписувала за ГОСТ 34.311 — бібліотека 2020 року іншого не вміла. Тепер алгоритм визначається автоматично, тож ключі зі свіжими сертифікатами почнуть підписуватись за ДСТУ 7564 без жодних змін у застосунку. Якщо приймаюча сторона до цього не готова, зафіксуйте попередню поведінку явно:

ESignModule.forRoot({ signAlgo: SignAlgo.DSTU4145WithGOST34311 })

Для порівняння: Електронний кабінет ДПС наразі теж примусово тримає ГОСТ 34.311 для всіх — віддає прапорець GET /ws/api/crypto/public_sign/hashAlgo і перемкне клієнтів централізовано, коли буде готовий.

Апаратні носії

Перелік носіїв працює як у класичному EUSignCP і клієнті ДІЇ: mediaTypes() один раз віддає усі типи, які знає агент (без опитування пристроїв), а mediaDevices(type) опитує підключені пристрої лише обраного типу. Порожній перелік пристроїв означає, що носія цього типу не підключено, а не помилку. Публічний GetKeyMedias бібліотеки, який опитує пристрої всіх ~35 типів одразу з завантаженням PKCS#11-модулів, не використовується: саме він робив форму апаратного ключа повільною (на Mac з агентом 1.3.1 — понад 10 с на виклик, форма робила два; тепер типи ~0,2 с, пристрої обраного типу ~0,04 с). Ініціалізація апаратної бібліотеки зі сховищем сертифікатів ЦСК займає близько 0,1 с і лишається без змін.

Серед типів є псевдоносій «файлова система» — ключ файлом на диску, який читає агент. Якщо потрібні лише апаратні носії, обмежте перелік:

ESignModule.forRoot({
  allowedKeyMediaTypes: [
    'е.ключ ІІТ Алмаз-1К',
    'е.ключ ІІТ Кристал-1',
    'ID-карта громадянина (БЕН)',
  ],
})

Розмір бандла

Бібліотека ІІТ важить близько 9 МБ і підключається динамічним import(), тому збирач виносить її в окремий чанк (~1.1 МБ у стисненому вигляді). Чанк завантажується при першій ініціалізації підпису, а не при старті застосунку — початковий бандл від пакета майже не зростає.

У режимі debug: true сервіс кладе себе у window.eSign, щоб з консолі можна було дістатись до модуля бібліотеки та створених екземплярів (див. скрипти діагностики в репозиторії).

Оновлення переліку ЦСК та сертифікатів

Файли CAs.json і CACertificates.p7b постачаються з пакетом. Щоб оновити їх у репозиторії бібліотеки:

./scripts/update-ca-certificates.sh

Скрипт завантажує офіційні набори з iit.com.ua та czo.gov.ua, об'єднує їх з наявним у репозиторії (прострочені сертифікати потрібні для перевірки раніше створених підписів) і оновлює обидва проєкти. Після цього — підняти версію пакета та опублікувати.

Застосунок може не залежати від релізів бібліотеки: достатньо вказати в caPath і caCertificatesPath адреси власного бекенда, який роздає ці файли.

Розробка

npm run build_lib          # збірка бібліотеки в dist/e-sign
npm run build_and_start    # збірка + запуск тестового застосунку
npm run publish_lib        # збірка та публікація

Бібліотека ІІТ підключається з локального архіву vendor/euscp-*.tgz, бо в публічному реєстрі npm ім'я euscp зайняте сторонньою заглушкою. Щоб оновити версію, покладіть новий архів у vendor/ та виконайте npm i ./vendor/euscp-<версія>.tgz.