ZDigitalSignature

Надстройка над скрпиптом cadesplugin от КриптоПРО для работы с цифровой подписью

В основе использует библиотеку cadesplugin-crypto-pro-api (в ней тот же код, что и в примерах на сайте КриптоПРО, только с поддержкой JS модулей)

Требования для работы

1. Купить лицензию ПО КРИПТО-ПРО -> СКЗИ "КриптоПро CSP/JCP" -> "КриптоПро версии 5.0"
2. Установить КриптоПРО CSP 5.0
3. Установить плагин для браузера
4. Сгенерировать и установить сертификат
5. Дать плагину в браузере права на доступ к локальным файлам. (Для Chrome: Плагины -> CryptoPro Extension for CAdES Browser Plug-in -> Сведения, поставить галочку напротив пункта Разрешить открывать локальные файлы по ссылкам, для прода это не трубется)
6. Проверить работу всего установленного ПО при помощи пункта Проверить работу плагина в меню плагина (п.3)
7. Современный браузер на Chromium

Для корректной работы в demo и dev режиме необходимо дать плагину в браузере права на доступ к локальным файлам. (п.5)

Демо режим

Запустить и проверить работу, в том числе проверить настройки ПО, можно при помощи страницы ./dist/demo/index.html.
Необходимо открыть эту страницу в браузере, ПО загрузится автоматически.

$3

npm i z-digital-signature

Пример работы с библиотекой

``TypeScript

import ZDigitalSignature from './path-to-lib'

const sig = new ZDigitalSignature({
loadingTries: 20,
loadingTriesTimeout: 500
})

// Запускаем проверку браузера
const plugin: ZDigitalSignatureLoadResponse = await sig.load({
// callback для возможности выбора необходимого сертификата пользователем. Вызывается 1 раз в процессе загрузки
selectSert: (serts: Array, callback: CallableFunction) => {
// Даём пользователю возможность выбрать сертификат
// Для примера тут мы просто выбираем первый сертификат из списка
const sert: ZDigitalSignatureSert = serts.find(sert => !!sert)

// Возвращаем в библиотеку, выбранный пользователем, сертификат при помощи callback функции
callback(sert)
},
// callback для отображения статуса загрузки. Вызывается несколько раз (по 1 разу на каждый этап загрузки)
onChangeStatus: (message: string) => {
// Показываем пользователю текущий статус загрузки ПО
alert(message)
}
}).catch((e: any) => {
// Показываем пользователю ошибку загрузки, если такая произошла
alert(Ошибка загрузки: ${e.message})
})

// Параметры подписи
const signData = 'SGVsbG8gd29ybGQ=', // Документ в виде Base64 строки
docName = 'Example document namne', // Наименование документа, который подписываем
sigType = true, // откреплённая подпись
signOption = ZDigitalSignatureBase64SignOption.CAPICOM_CERTIFICATE_INCLUDE_END_ENTITY_ONLY // = 2

// Подпись Base64 строки
const sign: string = await sig.signBase64(signData, docName, sigType, signOption).catch((e: any) => alert(e.message))
// Далее можно работать со строкой подписи
console.log('sign: ', sign)

// Проверка корректности подписи
const isValid: boolean = await sig.verifyBase64(sign, signData, sigType).catch((e: any) => alert(e.message))
console.log('isValid: ', isValid)

`

API

#### Enums and constants

- sigType - Тип подписи
- true - откреплённая (по умлочанию)
- false - прикреплённая
- ZDigitalSignatureBase64SignOption - Параметр, определяющий способ подписи
- 0 - CAPICOM_CERTIFICATE_INCLUDE_CHAIN_EXCEPT_ROOT - Сохраняет все сертификаты цепочки за исключением корневого
- 1 - CAPICOM_CERTIFICATE_INCLUDE_WHOLE_CHAIN - Сохраняет полную цепочку
- 2 - CAPICOM_CERTIFICATE_INCLUDE_END_ENTITY_ONLY - Сертификат включает только конечное лицо (по умлочанию)

#### Методы

Синтаксис: ZDigitalSignature.[method] (params)

- constructor - Создание нового объекта ZDigitalSignature

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature({ loadingTries, loadingTriesTimeout });
`

Возвращаемое значение: ZDigitalSignature Object

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| ------------------- | ------- | -------------- | --------------------- | ----------------------------------------------------------------- |
| loadingTries | number | Нет | 20 | Количество попыток загрузки КриптоПро CSP BrowserPlugin |
| loadingTriesTimeout | number | Нет | 500 | Время ожидания одной попытки загрузки КриптоПро CSP BrowserPlugin |

Итоговое время загрузки при 100% неудачных попытках будет = loadingTries * loadingTriesTimeout sec

---

- load - Загрузка и проверка корректности подключаемого ПО КриптоПРО

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const PluginData: ZDigitalSignatureLoadResponse = await ZDSignature.load(({
selectSert: (serts: Array, callback: CallableFunction) => callback(serts.find(s => !!s)),
onChangeStatus: (message: string) => console.log(Статус загрузки: -${message})
})).catch((e: any) => console.log(Ошибка загрузки: ${e.message}))
`

Возвращаемое значение: Promise<ZDigitalSignatureLoadResponse>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | ---------------- | -------------- | --------------------- | --------------------------------------------- |
| selectSert | CallableFunction | Нет | null | Callback для выбора сертификата пользователем |
| onChangeStatus | CallableFunction | Нет | null | Callback для возврата статуса загрузки |

---

- signBase64 - Подписывает строку в формате base64

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ=',
docName = 'Example document namne',
sigType = true,
signOption = ZDigitalSignatureBase64SignOption.CAPICOM_CERTIFICATE_INCLUDE_END_ENTITY_ONLY // = 2

const sign: string = await ZDSignature.signBase64(signData, docName, sigType, signOption).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | --------------------------------- | -------------- | --------------------- | --------------------------------------------- |
| signData | string | Да | null | Строка в формате base64, которую подписываем |
| docName | string | Нет | null | Наименование документа для подписи |
| sigType | boolean | Нет | true | Тип подписи |
| signOption | ZDigitalSignatureBase64SignOption | Нет | 2 | Параметр, определяющий способ подписи |

---

- verifyBase64 - Проверяет корректность подписи строки в формате base64

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature(),
signData = 'SGVsbG8gd29ybGQ=',
sigType = true,

// const sign: string = await sig.signBase64(...)

const isValid: boolean = await ZDSignature.verifyBase64(sign, signData, sigType).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<boolean>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | ---------------- | -------------- | --------------------- | -------------------------------------------- |
| sign | string | Да | null | Подпись, полученная из метода signBase64 |
| signData | string | Да | null | Строка в формате base64, которую подписывали |
| sigType | boolean | Нет | true | Тип подписи |

---

- getBase64Hash - Возвращает хеш значения строки в base64 по алгоритму GOST_3411_2012_512

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ='

const hash: string = await ZDSignature.getBase64Hash(signData).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | ---------------- | -------------- | --------------------- | ----------------------- |
| signData | string | Да | null | Строка в формате base64 |

---

- loadSerts - Загружает и возвращает список сетификатов с ПК пользователя

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()

const serts: Array = await this.loadSerts().catch(e => alert(e.message))
`

Возвращаемое значение: Promise<Array<ZDigitalSignatureSert>>

---

- loadSert - Устанавливает сертификат, которым будет происходить подпись

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()

const serts: Array = await this.loadSerts().catch(e => alert(e.message))
// Выбираем первый сертификат из списка (для примера)
const sert: ZDigitalSignatureSert = serts.find(s => !!s)

await ZDSignature.loadSert(sert).catch(e => alert(e.message))
`

Возвращаемое значение: Promise<ZDigitalSignatureSert>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | --------------------- | -------------- | --------------------- | -------------------------------- |
| sert | ZDigitalSignatureSert | Да | null | Выбранный сертификат для подписи |

---

- isReady - Проверяет готовность ПО и сертификатов к подписи, выбрасывает соответствующую ошибку

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const isReady = await ZDSignature.isReady().catch(e => {
alert(e.message)
return false
})
`

Возвращаемое значение: Promise<boolean>

---

- getSert - Находит и возвращает сертификат по его отпечатку

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const thumbprint = 'aweqweqweqweqweqweqweqwe'
await ZDSignature.getSert(thumbprint).catch(e => alert(e.message))
`

Возвращаемое значение: Promise<ZDigitalSignatureSert|null>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | ------ | -------------- | --------------------- | --------------------- |
| thumbprint | string | Да | null | Отпечаток сертификата |

---

- signFile - Подписывает файл в формате base64

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ=',
sigType = true,
signOption = ZDigitalSignatureBase64SignOption.CAPICOM_CERTIFICATE_INCLUDE_WHOLE_CHAIN // = 1

const sign: string = await ZDSignature.signFile(signData, sigType, signOption).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | --------------------------------- | -------------- | --------------------- | ------------------------------------------- |
| signData | string | Да | null | Файл в формате base64, который подписываем |
| sigType | boolean | Нет | true | Тип подписи |
| signOption | ZDigitalSignatureBase64SignOption | Нет | 2 | Параметр, определяющий способ подписи |

---

- signXml - Подписывает файл в формате base64

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = '',
signOption = ZDigitalSignatureXmlSignOption.CADESCOM_XML_SIGNATURE_TYPE_ENVELOPED // = 0

const sign: string = await ZDSignature.signXml(signData, signOption).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| -------------- | ------------------------------ | -------------- | --------------------- | ----------------------------------------- |
| signData | string | Да | null | Строка в формате XML, которую подписываем |
| signOption | ZDigitalSignatureXmlSignOption | Нет | 2 | Параметр, определяющий тип подписи |

---

- signHash512 - Подписывает хеш-сумму файла (Гост 3411_2012_512)

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ=',
sigType = true,
signOption = ZDigitalSignatureBase64SignOption.CAPICOM_CERTIFICATE_INCLUDE_WHOLE_CHAIN // = 1

const hash: string = await ZDSignature.getBase64Hash(signData).catch((e: any) => alert(e.message))

const sign: string = await ZDSignature.signHash512(hash, signOption).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| ------------ | --------------------------------- | -------------- | --------------------- | ------------------------------------- |
| hash | string | Да | null | Хеш base64 строки |
| signOption | ZDigitalSignatureBase64SignOption | Нет | 2 | Параметр, определяющий способ подписи |

---

- signHash256 - Подписывает хеш-сумму файла (Гост 3411_2012_256)

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ=',
sigType = true,
signOption = ZDigitalSignatureBase64SignOption.CAPICOM_CERTIFICATE_INCLUDE_WHOLE_CHAIN // = 1

const hash: string = await ZDSignature.getBase64Hash(signData).catch((e: any) => alert(e.message))

const sign: string = await ZDSignature.signHash256(hash, signOption).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| ------------ | --------------------------------- | -------------- | --------------------- | ------------------------------------- |
| hash | string | Да | null | Хеш base64 строки |
| signOption | ZDigitalSignatureBase64SignOption | Нет | 2 | Параметр, определяющий способ подписи |

---

- coSignHash512 - Добавление параллельной подписи (Гост 3411_2012_512)

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ=',
signOption = ZDigitalSignatureXmlSignOption.CADESCOM_XML_SIGNATURE_TYPE_ENVELOPED // = 0

const hash: string = await ZDSignature.getBase64Hash(signData).catch((e: any) => alert(e.message))
const sign: string = await ZDSignature.signHash512(hash, signOption).catch((e: any) => alert(e.message))

const coSign: string = await ZDSignature.coSignHash512(hash, sign, signOption).catch((e: any) => alert(e.message))
`

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| ------------ | ------------------------------ | -------------- | --------------------- | -------------------------------------- |
| hash | string | Да | null | Хеш base64 строки |
| signature | string | Да | null | Подпись полученная методом signHash512 |
| signOption | ZDigitalSignatureXmlSignOption | Нет | 2 | Параметр, определяющий тип подписи |

---

- coSignHash256 - Добавление параллельной подписи (Гост 3411_2012_256)

Использование:

`TypeScript
const ZDSignature = new ZDigitalSignature()
const signData = 'SGVsbG8gd29ybGQ=',
signOption = ZDigitalSignatureXmlSignOption.CADESCOM_XML_SIGNATURE_TYPE_ENVELOPED // = 0

const hash: string = await ZDSignature.getBase64Hash(signData).catch((e: any) => alert(e.message))
const sign: string = await ZDSignature.signHash256(hash, signOption).catch((e: any) => alert(e.message))

const coSign: string = await ZDSignature.coSignHash256(hash, sign, signOption).catch((e: any) => alert(e.message))
``

Возвращаемое значение: Promise<string>

Параметры:

| Наименование | Тип | Обязательность | Значение по умолчанию | Описание |
| ------------ | ------------------------------ | -------------- | --------------------- | -------------------------------------- |
| hash | string | Да | null | Хеш base64 строки |
| signature | string | Да | null | Подпись полученная методом signHash256 |
| signOption | ZDigitalSignatureXmlSignOption | Нет | 2 | Параметр, определяющий тип подписи |