Перевірка підпису КЕП та підписанта у контенті бізнес-процесу через API

🌐 Цей документ доступний українською та англійською мовами. Використовуйте перемикач у правому верхньому куті, щоб змінити версію.

1. Загальний опис

При інтеграції зі сторонніми системами на рівні бізнес-процесів є необхідність роботи з підписаними файлами які завантажуються або передаються в бізнес-процес цими системами. А саме, є необхідність впевнитись в цілісності цих файлів шляхом перевірки КЕП накладеного на ці файли. Отримати інформацію про підписанта для подальшої обробки або внесення в реєстри. Також є необхідність перегляду вмісту файлів-контейнерів.

2. Функціональні сценарії

  • Перевірка цілісності даних шляхом перевірки підпису з вказанням типу контейнера.

  • Отримання інформації про всіх підписантів даних

  • Отримання контенту з підписаного масиву даних.

3. Ролі користувачів

  • Моделювальник

4. Загальні принципи та положення

  • Дані опрацьовуються в скрипт-задачах бізнес-процесу.

  • Отримання даних з сторонніх джерел поза межами цього дизайну.

  • Байтові дані між системами передаються закодованими за допомогою Base64

  • Формат за замовченням використовується CAdES-X-Long.

  • Дані і підпис в даній ітерації завжди приходять в одному масиві даних.

  • Імплементація різних форматів валідація поза межами цього дизайну

  • Підписання файлів поза межами цього дизайну.

  • Імплементація алгоритмів по роботі з підписами відбувається за допомогою ІІТ-бібліотеки

5. Глосарій та акроніми

Контейнер - тип результуючого файлу. Розрізняються такі контейнери XAdES (xml), PAdES (pdf), CAdES (p7s), ASiC (asic). Найбільш сучасним і рекомендованим є контейнер типу ASiC.

ASiC - особливістю даного контейнеру є те що він побудований як архів для зберігання файлів і єдиний з перелічених дозволяє зберігати декілька файлів в різних форматах.

Формат - алгоритм який застосовується для підписання даних (XAdES-B-LT/CAdES-X-Long/CAdES-BASE/PAdES-B-LT) рекомендованим форматом є CAdES-X-Long

Тип підпису - розрізняється два типи підпису відокремлений (detached) та enveloped (вбудований).

Терміни файл і дані в даному дизайні взаємозамінні.

6. Приклади моделювання

6.1. Приклад моделювання БП з ASiC контейнером в якості вхідного параметра який містить декілька файлів

submission form

Приклад скриптової задачі
def formData = submission('start_event').formData
def file = formData.prop('signed_data').value()

def allSignInfo = signature_details(file, SignFormat.ASiC).getAllSignInfo()
for (signInfo in allSignInfo) {
    if (signInfo.subjDRFOCode == null) {
        println "DRFO should be present"
    }
}

def allFiles = get_content(file, SignFormat.ASiC).getAllContent()
for (singleFile in allFiles) {
    set_variable(singleFile.getReference(), singleFile.getReferenceData())
}

6.2. Приклад моделювання БП з отриманням p7s контейнера з вбудованим підписом як частина даних із зовнішнього API

external system

Приклад відповіді сторонньої системи
{
    "name": "Ololow",
    "day-of-birth": "01/01/01",
    "request": "dGVzdCBkYXRh",
    "request_received": "20/02/14"
}
Приклад скриптової задачі
def containerType = validationResult.prop('container').value()

def info = signature_details(request, containerType).getSignInfo()

if (info.subjDRFOCode == null) {
    println "DRFO should be present"
}

originRequestDate = signature_content(request, containerType).getContent().getData()

def requestBytes = Base64.decode(originRequestDate)

save_digital_document(requestBytes, 'request.pdf')

set_variable('fileContent', originRequestDate)

7. Делегат для валідації

7.1. Параметри делегату

Назва параметру Опис Тип Тип даних

data

Дані які включають в себе підпис в форматі Base64

Вхідний

String

container

Перелік доступних для використання типів файлів

Вхідний

Enum (ASiC/CAdES)

result

Результат валідації

Вихідний

ValidatioResult

7.2. REST API

POST /api/esignature/validate

Приклад тіла запиту
{
  "data": "dGVzdCBkYXRh",
  "container": "CAdES/ASiC/XdES/..."
}
Таблиця 1. Структура тіла відповіді
Json Path Тип Опис

$result.isValid

boolean

Результат перевірки даних

$result.container

String

Тип контейнеру

$.error.code

String

Відповідний код статусу

$.error.message

String

Деталі та опис помилки

$.error.localizedMessage

String

Локалізовані деталі та опис помилки

7.3. Низькорівневий дизайн

Для валідації підписів ASiC контейнерів відбувається отримання кількості підписантів за допомогою EndUser::ASiCGetSignsCount(base64Data), а далі перевіряється валідність кожного EndUser::ASiCVerify(index, base64Data)

Для CAdES використовується EndUser::VerifyInternal(base64Data)

8. signature_details(<string|data>, <enum|dataFormat>)

8.1. JUEL функція

Назва параметру Опис Тип Тип даних

data

Дані які включають в себе підпис в форматі Base64

Вхідний

String

container

Перелік доступних для використання типів файлів

Вхідний

Enum (ASiC/CAdES)

signInfo

Деталі про підпис

Вихідний

SignatureInfo
Структури для отримання контенту в БП
Зображення 1. Структури для отримання контенту в БП
Таблиця 2. Структура SignDetails
Json Path Тип Опис

issuer

String

Видавець сертифікату

issuerCN

String

Назва видавця сертифікату

serial

String

Серійний номер сертифікату

subject

String

Загальна інформація про власника сертифікату

subjCN

String

Ім’я власника сертифікату

subjOrg

String

Організація власника сертифікату

subjOrgUnit

String

Підрозділ власника сертифікату

subjTitle

String

Посада власника сертифікату

subjState

String

Регіон/область власника сертифікату

subjLocality

String

Локаль підписанта

subjFullName

String

ПІБ підписанта

subjAddress

String

Адреса підписанта

subjPhone

String

Телефон підписанта

subjDNS

String

DNS-ім’я чи інше технічного засобу

subjEDRPOUCode

String

ЄДРПОУ підписанта

subjDRFOCode

String

ДРФО підписанта

8.2. REST API

POST /api/esignature/info

Приклад тіла запиту
{
  "data": "dGVzdCBkYXRh",
  "container": "CAdES/ASiC/XdES/..."
}
Таблиця 3. Структура тіла відповіді
Json Path Тип Опис

$.info[]

array[SignatureInfo]

Масив даних що містить в себе деталі про кожен підпис

$.error.code

String

Відповідний код статусу

$.error.message

String

Деталі та опис помилки

$.error.localizedMessage

String

Локалізований опис

8.3. Низькорівневий дизайн

Для даних у форматі ASiC передбачено можливість накладання декількох підписів, тому при отриманні інформації про підпис, повертається масив з деталями про кожен накладений на дані підпис.

Приклад логіки валідації ASiC
IntStream.rangeClosed(0, endUser.ASiCGetSignsCount(data))
                .mapToObj(index -> endUser.ASiCVerify(index, data))
                .collect(Collectors.toList());

Для даних в форматі CAdES використовується EndUser::VerifyInternal(base64Data) та повертається деталі з об’єкту EndUserSignInfo як єдиний елемент в масиві.

9. signature_content(<string|data>, <enum|dataFormat>)

9.1. JUEL функція

Назва параметру Опис Тип Тип даних

data

Дані які включають в себе підпис в форматі Base64

Вхідний

String

container

Перелік доступних для використання типів файлів

Вхідний

Enum (ASiC/CAdES)

response

Обʼєкт з даними

Вихідний

SignData
Структури для отримання контенту в БП
Зображення 2. Структури для отримання контенту в БП

9.2. REST API

POST /api/esignature/content

Приклад тіла запиту
{
  "data": "dGVzdCBkYXRh",
  "container": "CAdES/ASiC/XdES/..."
}
Таблиця 4. Структура тіла відповіді
Json Path Тип Опис

$.content[]

array[Content]

Вміст контейнеру

$.error.code

String

Відповідний код статусу

$.error.message

String

Деталі та опис помилки

$.error.localizedMessage

String

Локалізовані деталі та опис помилки

9.3. Низькорівневий дизайн

Для ASiC контейнеру отримання переліку всіх файлів в контенйері відбувається за допомогою EndUser::ASiCGetSignReferences(index, base64Data) для кожного індексу, а отримання контенту за допомогою EndUser::ASiCGetReference(reference)

Для CAdES контейнерів дані є частина вихідного параметру EndUser::VerifyInternal(base64Data)::GetData()

10. Оновлення бібліотеки ІІТ

  1. Криптобібліотека надається у вигляді посилання на архів https://iit.com.ua/download/EUSignCP-Java-20230629.zip

  2. Архів з бібліотекою складається з папок

    • Documentation – актуальна документація для поточної версії криптобібліотеки;

    • Modules та\або Installs – актуальні модулі та\або інсталяційні пакети поточної версії криптобібліотеки;

    • Usage – актуального прикладу використання криптобібліотеки. Документація складається з настанови для системного програміста (містить загальну інформацію по бібліотеці: як підключати, налаштовувати та використовувати бібліотеку) та додатку (містить опис функцій та параметрів).

  3. Оновлення, що містять не критичні доопрацювання, надаються за запитом на пошту supp@iit.com.ua (в листі треба вказати номер діючого договору тех. підтримки). Про критичні оновлення інформуємо листом на пошту, яка вказана в контактах для організації

11. Високорівневий план розробки

12. Технічні експертизи

  • BE (java)

13. План розробки

  • Оновлення бібліотеки ІІТ

  • Розширення DSO відповідними точками інтеграції

  • Створення делегату для валідації

  • Додавання JUEL-функцій

  • Додавання утілітарної функції для кодування і декодування Base64

  • Розробка референтних прикладів