z-digital-signature v0.0.5

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. Необходимо открыть эту страницу в браузере, ПО загрузится автоматически.

Установка

npm i z-digital-signature

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

    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<ZDigitalSignatureSert>, 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

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

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

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

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

  Параметры:

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

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

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

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

  const ZDSignature = new ZDigitalSignature()
  const PluginData: ZDigitalSignatureLoadResponse = await ZDSignature.load(({
      selectSert:     (serts: Array<ZDigitalSignatureSert>, 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

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

  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

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

  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

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

  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 - Загружает и возвращает список сетификатов с ПК пользователя

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

  const ZDSignature = new ZDigitalSignature()
  
  const serts: Array<ZDigitalSignatureSert> = await this.loadSerts().catch(e => alert(e.message))

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

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

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

  const ZDSignature = new ZDigitalSignature()
  
  const serts: Array<ZDigitalSignatureSert> = 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 - Проверяет готовность ПО и сертификатов к подписи, выбрасывает соответствующую ошибку

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

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

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

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

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

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

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

  Параметры:

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

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

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

  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

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

  const ZDSignature = new ZDigitalSignature()
  const signData = '<xml ...>',
      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)

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

  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)

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

  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)

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

  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)

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

  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	Параметр, определяющий тип подписи