Signature manager for CryptoPro CSP 5.0
npm install z-digital-signatureНадстройка над скрпиптом 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.
Необходимо открыть эту страницу в браузере, ПО загрузится автоматически.
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
// Даём пользователю возможность выбрать сертификат
// Для примера тут мы просто выбираем первый сертификат из списка
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)
`
#### 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Статус загрузки: -${message}
const ZDSignature = new ZDigitalSignature()
const PluginData: ZDigitalSignatureLoadResponse = await ZDSignature.load(({
selectSert: (serts: Array
onChangeStatus: (message: string) => console.log()Ошибка загрузки: ${e.message}
})).catch((e: any) => console.log())`
Возвращаемое значение: 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
`
Возвращаемое значение: Promise<Array<ZDigitalSignatureSert>>
---
- loadSert - Устанавливает сертификат, которым будет происходить подпись
Использование:
`TypeScript
const ZDSignature = new ZDigitalSignature()
const serts: Array
// Выбираем первый сертификат из списка (для примера)
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 | Параметр, определяющий тип подписи |