@it-enterprise/digital-signature 1.2.0 → 1.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@it-enterprise/digital-signature",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "digital signature",
   "private": false,
   "main": "src/index.js",
@@ -15,6 +15,7 @@
   },
   "homepage": "https://gitlab.com/it-enterprise/npm-packages/digital-signature#readme",
   "devDependencies": {
+    "@babel/eslint-parser": "^7.18.9",
     "eslint": "^7.18.0"
   }
 }

package/readme.md

@@ -7,7 +7,7 @@
 Install-Package ItEnterprise.DigitalSignature.Web
 ```
 
-Подключение .net core
+Подключение
 
 ```c#
 using ItEnterprise.DigitalSignature.Web;
@@ -20,9 +20,12 @@ namespace TestApp.Web.NetCore
     public void ConfigureServices(IServiceCollection services)
     {
       services.AddDigitalSignature(builder => builder
-        // Ссылка на веб-сервисы. Необходимо для обновления коревых сертификатов и списка ЦСК
-        .SetWsUri("https://m.it.ua/ws")
-        .SetConfig(new DigitalSignatureConfiguration
+        .AddCertiticateUpdatesService(
+          // Ссылка на веб-сервисы. Необходимо для обновления коревых сертификатов и списка ЦСК
+          "https://m.it.ua/ws",
+          // Получать значение параметра GlSign через веб-расчёт
+          false
+        ).SetConfig(new DigitalSignatureConfiguration
         {
           // Использовать нативные библиотеки. true, если будет использоваться C# API ЕЦП. Нативные библиотеки необходимо устанавливать отдельными nuget пакетами
           UseNativeLibraries = false,
@@ -41,37 +44,6 @@ namespace TestApp.Web.NetCore
 }
 ```
 
-Подключение .net framework
-
-```c#
-using ItEnterprise.DigitalSignature.Web;
-using ItEnterprise.DigitalSignature.Models;
-
-namespace TestApp.Web.NetFramework
-{
-	public class Global : System.Web.HttpApplication
-	{
-		protected void Application_Start(object sender, EventArgs e)
-		{
-			this.UseDigitalSignature(ds => ds
-        // Путь, по которому будет доступно API ЕЦП
-				.MapRoute("api/ds/")
-        // Ссылка на веб-сервисы. Необходимо для обновления коревых сертификатов и списка ЦСК
-				.SetWsUri("https://m.it.ua/ws")
-				.SetConfig(new DigitalSignatureConfiguration
-				{
-          // Использовать нативные библиотеки. true, если будет использоваться C# API ЕЦП. Нативные библиотеки необходимо устанавливать отдельными nuget пакетами
-					UseNativeLibraries = false,
-					GlSign = new GlSignInfo {
-            // Разрешать использовать тестовые ключи
-            AllowTestKeys = true 
-          }
-				}));
-		}
-	}
-}
-```
-
 # Установка
 
 [@it-enterprise/digital-signature](https://www.npmjs.com/package/@it-enterprise/digital-signature)
@@ -94,34 +66,71 @@ import {
 
 # Инициализация
 
-## Для GraphQL приложений
-
+Смена типа библиотеки
 ```javascript
-import auth from '@it-enterprise/jwtauthentication';
-
 const ds = new DigitalSignature(
-  new Models.GraphQlSettingProvider(
-    "uk", // Язык ошибок
-    userId, // id пользователя (для сохранения ключей и предпочитаемого типа ключа)
-    "https://m.it.ua/GraphQlServer/", // Адрес сервера GraphQl
-    "https://m.it.ua/ws/", // Адрес веб-сервисов
-    auth) // Библиотека @it-enterprise/jwtauthentication
+  new Models.DefaultSettingProvider(
+    "uk", // Язык ошибок (строка, или функция, возвращающая строку)
+    userId, // id пользователя (для сохранения ключей и предпочитаемого типа ключа) (строка, или функция, возвращающая строку)
+    location.pathname + "api/ds/") // Путь к API ЕЦП
   );
-await ds.initialise();
+Возвращает текущий тип ключа (файловый, аппаратный, облачный)
+const currentKeyType = await ds.initialise();
+```
+Сменить тип библиотеки
+```javascript
+/** Подпись файловыми ключами, через облачные сервисы  */
+export const DigitalSignatureLibraryTypeJS = 0;
+/** Подпись аппартными ключами */
+export const DigitalSignatureLibraryTypeSW = 1;
+/**
+ * Типы библиотеки
+ */
+export const DigitalSignatureLibraryType = {
+  /** Подпись файловыми ключами и через облачные сервисы */
+  JS: DigitalSignatureLibraryTypeJS,
+  /** Подпись аппартными ключами */
+  SW: DigitalSignatureLibraryTypeSW
+};
+
+await ds.setLibraryType(type);
 ```
 
-## Для остальных приложений
+# Центры сертификации ключей
 
+Получение списка сертификации ключей
 ```javascript
-const ds = new DigitalSignature(
-  new Models.DefaultSettingProvider(
-    "uk", // Язык ошибок
-    userId, // id пользователя (для сохранения ключей и предпочитаемого типа ключа)
-    location.pathname + "api/ds/", // Путь к API ЕЦП
-    glSign) // Значение глобального параметра GlSign в виде строки или обьекта Models.GlSign
-  );
-await ds.initialise();
+const cas = await ds.getCAs();
 ```
+Установить центр сертификации ключей
+```javascript
+// Предоставить возможность пользователю выбирать ЦСК. Для автоматического определения ЦСК установить значение null
+const ca = cas[0];
+await ds.setCA(ca);
+
+```
+Проверить, поддерживает ли ЦСК автоматическую загрузку сертификатов  
+Если ЦСК не поддерживает автоматическую загрузку сертификатов, нужно предоставить возможность пользователю вручную указать сертификаты  
+```javascript
+const needCerts = ds.needPrivateKeyCertificates();
+```  
+Структура объекта CASettings
+```javascript
+class CASettings {
+    // Названия ЦСК (обычно используется первое из списка)
+    issuerCNs: Array<string>;
+    address: string;
+    ocspAccessPointAddress: string;
+    ocspAccessPointPort: string;
+    cmpAddress: string;
+    tspAddress: string;
+    tspAddressPort: string;
+    directAccess: boolean;
+    certsInKey: boolean;
+    cmpCompatibility: number;
+    qscdSNInCert: boolean;
+}
+```  
 
 # Файловые ключи
 
@@ -190,50 +199,87 @@ const keyInfo = await ds.readHardwareKey(
 );
 ```
 
-# MobileID
+# Облачные ключи
 
-Считывание ключа
+Провайдеры облачныч ключей есть 2х видов: работающие через QR код (Дія.Підпис, SmartID, CloudKey) и через ID пользователя (DepositSign, ESign, Вчасно)  
+Получение списока провайдеров облачных ключей
 
 ```javascript
-const keyInfo = await ds.readPrivateKeySIM(
-  // Номер телефона пользователя
-  phone,
-  // Оператор. Kyivstar - 1, Vodafone - 2, Lifecell - 3
-  operatorId,
-  // Номер ключа. Для Kyivstar всегда 0, для Vodafone и Lifecell: физ. лицо - 1, юр. лицо - 2
-  keyId,
-  // Получать информацию о сертификатах пользователя. 
-  // true - поля ownerInfo и certificates будут заполены, но пользователь получит дополнительный запрос на подписание
-  // false - поля ownerInfo и certificates будут пустыми, но пользователь не получит дополнительный запрос на подписание
-  false);
+const ksps = ds.KSPs;
 ```
 
-# DepositSign
+Содержимое обьекта KSP
 
-Считывание ключа
+```javascript
+class KSPSettings {
+    // Название провайдера
+    name: string;
+    // Провайдер работает через QR код или через ID пользователя
+    needQRCode: boolean;
+    // Тип ID пользователя (имя пользователя/телефон/email)
+    clientIdType?: EndUserKSPClientIdType;
+    ksp: EndUserKSP;
+    address?: string;
+    port?: string;
+    directAccess?: boolean;
+    clientIdPrefix?: string;
+    confirmationURL?: string;
+    mobileAppName?: string;
+    pollingInterval?: number;
+    systemId?: string;
+}
+```
+
+Для ключей, работающих через QR код, после инициализации библиотеки нужно подписаться на событие подтверждения операции  
 
 ```javascript
-const keyInfo = await ds.readPrivateKeyDepositsign(
-  // Идентификатор пользователя (номер телефона или email)
-  phone,
-  // Получать информацию о сертификатах пользователя. 
-  // true - поля ownerInfo и certificates будут заполены, но пользователь получит дополнительный запрос на подписание
-  // false - поля ownerInfo и certificates будут пустыми, но пользователь не получит дополнительный запрос на подписание
-  false);
+ds.addConfirmKSPOperationEventListener(eventArgs => { ... });
+```
+
+Событие будет вызываться при:  
+1. Считывании ключа с getCerts = true  
+2. Подписании данных  
+
+**Важно!** При необходимости подписать несколько файлов, нужно передавать их в функцию подписания все за раз в массиве. Иначе пользователю придётся подтверждать подписание каждого файла отдельно  
+
+
+Структура объекта, приходящего в коллбек события  
+```javascript
+class EndUserConfirmKSPOperationEvent {
+    // Ссылка на подтверждение операции
+    url: string;
+    // QR код в формате data:image/bmp для подстановки в <img scr='...' />
+    qrCode: string;
+    // Название мобильного приложения, в котором нужно подтвердить выполнение операции
+    mobileAppName: string;
+    // Время, до которого действует ссылка
+    expireDate: Date;
+}
 ```
+QR код нужно отобразить пользовтелю, что бы он мог отсканировать его в приложении и подтвердить подписание  
+Для отображения QR кода можно использовать содержимое поля qrCode, либо сгенерировать его на основе ссылки из поля url  
+Для мобильных устройств должна быть возможность переходя по ссылке из поля url, для возможности сразу запустить соответствующее приложение  
 
-# Дiя
 
 Считывание ключа
 
 ```javascript
-const keyInfo = await ds.readPrivateKeyDiia(
-  // Получать информацию о сертификатах пользователя. 
-  // true - поля ownerInfo и certificates будут заполены, но пользователь получит дополнительный запрос на подписание
-  // false - поля ownerInfo и certificates будут пустыми, но пользователь не получит дополнительный запрос на подписание
-  false);
+// Предоставить пользователю возможность выбрать провайдера ключей
+const ksp = ds.KSPs[0];
+
+const keyInfo = await ds.readPrivateKeyKSP(
+  // Объект KSP из списка ds.KSPs
+  ksp
+  // Идентификатор пользователя - для провайдеров ключей, работающих через ID пользователя
+  // Для провайдеров ключей, работающих через QR код - null
+  userID,
+  // Получать информацию о сертификатах пользователя
+  // true - поля ownerInfo и certificates в keyInfo будут заполены, но пользователю нужно будет подтвердить дополнительную операцию подписания
+  // false - поля ownerInfo и certificates в keyInfo будут пустыми, но пользователь не получит дополнительный запрос на подписание
+  getCerts = false);
 ```
 
+
 # Сохранение ключей
 
 Сохранить ключ
@@ -262,16 +308,166 @@ await ds.removeStoredPrivateKeyInfo(
   keyId
 ```
 
-# Подписание
+# Создание подписей
+
+## Формат подписи
+
+Функции создания подписей поддерживают возможность выбирать формат контейнера подписи  
+Формат подписи указывается в опциональном параметре signFormat  
+По умолчанию используется формат подписи CAdES Detached  
+
+Структура объекта, описывающего формат подписи  
+
+```javascript
+class EndUserSignContainerInfo {
+    // Тип контейнера подписи
+    type: EndUserSignContainerType;
+    // Уточняющий тип подписи
+    subType: EndUserCAdESType | EndUserXAdESType | EndUserASiCType;
+    // Тип подписи в ASiC контейнере (только для ASiC контейнеров)
+    asicSignType: EndUserASiCSignType;
+}
+```
+Типы контейнеров подписи
+```javascript
+const EU_SIGN_CONTAINER_TYPE_CADES = 1;
+const EU_SIGN_CONTAINER_TYPE_XADES = 2;
+const EU_SIGN_CONTAINER_TYPE_PADES = 3;
+const EU_SIGN_CONTAINER_TYPE_ASIC = 4;
+enum EndUserSignContainerType {
+    // CMS подпись в двоичном формате. Используется по умолчанию
+    CAdES,
+    // Подпись в формате XML. Может содержать одновременно несколько наборов данных
+    XAdES,
+    // Подпись в PDF документе (Работает только с PDF файлами)
+    PAdES,
+    // Контейнер для подписей в виде ZIP-архива
+    ASiC
+}
+```
+Типы подписей CAdES
+```javascript
+const EU_CADES_TYPE_DETACHED = 1;
+const EU_CADES_TYPE_ENVELOPED = 3;
+enum EndUserCAdESType {
+    // Подпись отдельно от данных (внешняя подпись). Используется по умолчанию
+    Detached,
+    // Подпись в одном контейнере с данными (внутренняя подпись)
+    Enveloped
+}
+```
+Типы подписей XAdES
+```javascript
+const EU_XADES_TYPE_DETACHED = 1;
+const EU_XADES_TYPE_ENVELOPED = 3;
+enum EndUserXAdESType {
+    // Подпись отдельно от данных (внешняя подпись)
+    Detached,
+    // Подпись в одном контейнере с данными (внутренняя подпись)
+    Enveloped
+}
+```
+Типы контейнеров ASiC
+```javascript
+const EU_ASIC_TYPE_S = 1;
+const EU_ASIC_TYPE_E = 2;
+enum EndUserASiCType {
+    // Простой контейнер, содержащий 1 файл с данными и 1 подпись
+    S,
+    // Расширенный контейнер, может содержать несколько файлов с данными и несколько подписей
+    E
+}
+```
+Типы подписей, которые могут содержаться в ASiC контейнере
+```javascript
+const EU_ASIC_SIGN_TYPE_CADES = 1;
+const EU_ASIC_SIGN_TYPE_XADES = 2;
+enum EndUserASiCSignType {
+    CAdES,
+    XAdES
+}
+```
+
+Пример использования формата подписи:
+```javascript
+const file = {
+  name: "file.pdf",
+  val: "ссылка на загрузку файла"
+};
+// Формат ASiC-S с подписью XAdES
+const asicsformat = {
+  type: EndUserSignContainerType.ASiC,
+  subType: EndUserASiCType.S,
+  asicSignType: EndUserASiCSignType.XAdES
+};
+// Формат PAdES
+const padesformat = {
+  type: EndUserSignContainerType.PAdES,
+};
+// Внутренняя CAdES подпись
+const cadesformat {
+  type: EndUserSignContainerType.CAdES,
+  subType: EndUserCAdESType.Enveloped
+};
+
+const asics = await ds.signFile(file, asicsformat);
+const pades = await ds.signFile(file, padesformat);
+const cades = await ds.signFile(file, cadesformat);
+```
+
+const signatures = await ds.signFile(files);
+
+## Формат передачи данных
+
+Все функции создания подписей поддерживают следующие форматы передачи данных:  
+1. Одиночный набор данных (в зависимости от функции - ссылка на загрузку файла, данные в base64 или Uint8Array и т.д.)
+2. Данные в массиве (данные как в п.1, только в массиве). Подписи так же будут возвращены в массиве
+3. Именованные данные (данные в объекте NamedData, содержащем имя набора данных и сами данные). Подпись так же будет возвращена в объекте NamedData
+4. Именованные данные в массиве (данные как в п.3, только в массиве). Результатом выполения функций будет являться массив обьектов NamedData с подписями  
+**Для лучшей поддержки всех форматов подписей и типов ключей, рекомендуется использовать формат из п.4**
+
+Структура объекта NamedData
+```javascript
+declare type NamedData = {
+    // Имя набора данных
+    name: string;
+    // В качестве параметра при создании подписи: в зависимости от функции - ссылка на загрузку файла, данные в base64 или Uint8Array и т.д.
+    // В качестве возвращаемого результата: контейнер с подписью
+    val: string | Uint8Array;
+};
+```
+Пример использования формата именованных данных
+```javascript
+const files = [{
+  name: "file1.docx",
+  val: "ссылка на загрузку первого файла"
+}, {
+  name: "file2.pdf",
+  val: "ссылка на загрузку второго файла"
+}];
+
+const signatures = await ds.signFile(files);
+console.log(signatures);
+// Результат
+[{
+  name: "file1.docx",
+  val: "подпись первого файла"
+}, {
+  name: "file2.pdf",
+  val: "подпись второго файла"
+}]
+```
+
+## Функции для создания подписей
 
 Подписание данных
 
 ```javascript
 const sign = await ds.signData(
-  // Данные в виде Uint8Array или строки base64. Можно передавать данные в массиве
+  // Данные в виде Uint8Array или строки base64
   data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false,
+  // Формат подписи
+  signFormat,
   // true - вернуть результат в виде массива байт,false - в виде строки base64. по умолчанию false
   false);
 ```
@@ -280,34 +476,30 @@ const sign = await ds.signData(
 
 ```javascript
 const sign = await ds.signFile(
-  // Ссылка на загрузку файла (например, с веб-сервисов). Можно передать массив ссылок
+  // Ссылка на загрузку файла (например, с веб-сервисов)
   data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false,
+  // Формат подписи. [Формат подписи]
+  signFormat,
   // true - вернуть результат в виде массива байт,false - в виде строки base64. по умолчанию false
   false);
 ```
 
-Подписание хеша
+Подписание хеша в формате CAdES Detached
 
 ```javascript
 const sign = await ds.signHash(
-  // Хеш в виде Uint8Array или строки base64. Можно передавать данные в массиве
-  data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false,
+  // Хеш в виде Uint8Array или строки base64
+  hash,
   // true - вернуть результат в виде массива байт,false - в виде строки base64. по умолчанию false
   false);
 ```
 
-Подписание хеша из файла
+Подписание хеша из файла в формате CAdES Detached
 
 ```javascript
 const sign = await ds.signFileHash(
-  // Ссылка на загрузку файла с хешем. Можно передать массив ссылок
+  // Ссылка на загрузку файла с хешем
   data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false,
   // true - вернуть результат в виде массива байт,false - в виде строки base64. по умолчанию false
   false);
 ```
@@ -316,28 +508,26 @@ const sign = await ds.signFileHash(
 
 ```javascript
 const sign = await ds.signDataEx(
-  // Данные в виде Uint8Array или строки base64. Можно передавать данные в массиве
+  // Данные в виде Uint8Array или строки base64
   data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false);
+  // Формат подписи
+  signFormat);
 ```
 
 Подписание файла с получением информации о подписи
 
 ```javascript
 const sign = await ds.signFileEx(
-  // Ссылка на загрузку файла (например, с веб-сервисов). Можно передать массив ссылок
+  // Ссылка на загрузку файла (например, с веб-сервисов)
   data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false);
+  // Формат подписи
+  signFormat);
 ```
 
-Подписание хеша с получением информации о подписи
+Подписание хеша в формате CAdES Detached с получением информации о подписи
 
 ```javascript
 const sign = await ds.signHashEx(
-  // Хеш в виде Uint8Array или строки base64. Можно передавать данные в массиве
-  data,
-  // true - внутренняя подпись, false - внешняя. по умолчанию false
-  false);
+  // Хеш в виде Uint8Array или строки base64
+  data);
 ```