.. _Integration_CryptoApi_CryptoApiConcept:

Как работать с Crypto API
#########################

Юридически значимый электронный документооборот требует формирования электронных подписей (ЭП).
Продукт поддерживает два способа формирования подписей:

* локальное подписание;
* серверное подписание.

Crypto API используется в Продукте для сценариев серверного подписания.

Серверное подписание предполагает, что сертификат для создания ЭП находится не на машине пользователя, а хранится на сервере.
В зависимости от того, какой криптопровайдер выбран (локальный, облачный, защищенное хранилище `КриптоПро HSM <https://cryptopro.ru/products/hsm>`_),
"сервером" может быть как машина, на которой развернут Crypto API, так и удаленный хост, на котором работает криптопровайдер.

Crypto API предоставляет единый программный интерфейс для доступа к выбранной реализации криптопровайдера.

.. note::
    По умолчанию Продукт поставляется с криптопровайдером на основе установленного на сервере `КриптоПро CSP <https://www.cryptopro.ru/products/csp>`_.

Как формировать исходящую подпись
*********************************

Общий порядок формирования исходящей ЭП следующий:

* Определить сертификат, с помощью которого будут подписаны данные.
  Для этого либо запросить список сертификатов и дать пользователю выбрать нужный, либо определить сертификат по отпечатку.
  Отпечаток может храниться в настройках пользователя во внешней системе.
* Создать и отправить запрос на формирование ЭП, передав выбранный сертификат и данные для подписания.
  Сертификат можно передать как с помощью отпечатка, так и в виде массива байт (содержимое cer-файла, без закрытого ключа).
* При необходимости создать и отправить запрос на улучшение ЭП.

Что делать с входящей подписью
*******************************

При получении входящей подписи с ней можно выполнить следующие действия:

* Проверить, если автоматическая проверка подписей отключена в настройках Продукта либо если нужно получить информацию о сертификате подписанта.
* Улучшить, если автоматическое улучшение подписей отключено в настройках Продукта.

| См. также:
| :ref:`Setup_Integration_AdvancedSetup_ValidationAndSignatures`

Как шифровать и расшифровывать данные
*************************************

Crypto API может использоваться для асимметричного шифрования и расшифровки данных, например, для обмена зашифрованными документами.

Для обмена зашифрованными документами нужно:

* Подписать документы с помощью сертификата *отправителя*.
* Зашифровать документы с помощью сертификата *получателя* на стороне *отправителя*. Шифрование происходит *открытым ключом* сертификата.
* Отправить зашифрованные документы и подписи к ним получателю.
* На стороне *получателя* расшифровать документы с помощью сертификата *получателя*. Расшифровка происходит *закрытым ключом* сертификата.
  Таким образом, прочитать документы сможет только владелец сертификата.
* Далее работать с расшифрованными документами и подписями к ним.