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] (params)

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