Описание и возможности API КриптоАРМ#

API КриптоАРМ позволяет встроить криптографические операции (подпись, шифрование, работу с сертификатами) прямо в ваше веб- или desktop-приложение. Это руководство подробно объясняет архитектуру протокола cryptoarm://, все доступные команды, форматы запросов и пошаговые сценарии интеграции. Вы узнаете, как настроить взаимодействие между вашим порталом и КриптоАРМ для безопасной обработки документов.

Содержание:

• Описание и возможности API КриптоАРМ
• Общая информация
• Доступные команды
• Сценарий выполнения команд для web-приложений
• Сценарий выполнения команд для локальных приложений
• Формат ссылки для web КриптоАРМ API
• Формат ссылки для локального варианта КриптоАРМ API
• Аутентификация
  • mTLS (авторизация по сертификату сервера)
  • OIDC (OpenID Connect)
  • Комбинированная (oidc:mtls)
  • Токен авторизации (customAuth)
• Описание запросов и ответов
  • POST-запрос
  • GET-запрос
  • Ответ
  • Объект Error
  • HTTP-коды

Общая информация#

КриптоАРМ поддерживает API с двумя возможными точками вызова:

• Локальное приложение на рабочем месте,
• Web-приложение (сервис).

При вызове операции через API приложение КриптоАРМ будет запущено и отобразит необходимый раздел с переданными параметрами. Команду можно ввести через адресную строку браузера (вы можете размещать их так же, как ссылки на веб-страницы) или в терминале.

Для взаимодействия используется зарегистрированный протокол cryptoarm://.

Доступные команды#

В таблице ниже перечислены все команды API. Кликните на название команды, чтобы перейти к детальному описанию, синтаксису и примерам JSON.

Сценарий выполнения команд для web-приложений#

1. Инициация операции

   • Пользователь заходит на портал (веб-приложение).
   • Выбирает объекты (например, список документов) и действие (например, подпись).

2. Генерация ссылки

   • Портал формирует и отображает (или автоматически перенаправляет) ссылку с протоколом cryptoarm://, содержащую идентификатор операции.
   • Опционально может быть передан тип аутентификации (authType) как query-параметр.

3. Запуск и запрос параметров

   • Если КриптоАРМ не запущен, система автоматически его запускает.
   • КриптоАРМ обращается к порталу, запрашивая JSON с параметрами для выполнения операции.
   • JSON генерируется на сервере веб-приложения.

4. Обработка команды

   • Полученный JSON анализируется.
   • В зависимости от типа операции, КриптоАРМ может выполнить дополнительные запросы к веб-приложению (например, загрузка документов).

5. Подтверждение пользователем

   • Пользователь проверяет детали операции и подтверждает её выполнение.
   • На время выполнения функционал приложения блокируется для предотвращения конфликтов.

6. Отправка результатов

   • Результаты операции (например, подписанные документы) передаются обратно на сервер веб-приложения.

Сценарий выполнения команд для локальных приложений#

1. Инициация операции

   • Пользователь открывает стороннее приложение с поддержкой КриптоАРМ API.
   • Выбирает объекты (например, документы) и действие (например, подпись).

2. Формирование JSON-запроса

   • Приложение генерирует JSON-объект с параметрами операции и передаёт его в КриптоАРМ (через CLI или API).

3. Запуск и обработка параметров

   • Если КриптоАРМ не запущен, он автоматически стартует.
   • Приложение может дополнительно запросить JSON с сервера (если часть параметров хранится удалённо).

4. Подтверждение пользователем

   • Пользователь проверяет детали операции и подтверждает её выполнение.
   • Функционал приложения блокируется до завершения операции.

5. Сохранение результатов

   • Результаты (например, подписанные файлы) сохраняются в локальную папку, указанную в параметрах операции.

Формат ссылки для web КриптоАРМ API#

cryptoarm://<command>/<URL>/?id=<id>[&authType=<authType>]

• cryptoarm:// - зарегистрированный протокол
• <command> - выполняемая команда
• <URL> - ссылка на получение JSON с параметрами, нужными для выполнения команды
• ?id=<id> - обязательный параметр. Идентификатор транзакции.
• &authType=<authType> - необязательный параметр. Тип аутентификации. Возможные значения:
• oidc — авторизация через OpenID Connect
• mtls — авторизация по сертификату (mTLS)
• oidc:mtls — комбинированная авторизация (OIDC + mTLS)

Формат ссылки для локального варианта КриптоАРМ API#

Вариант 1 (через файл):

cryptoarm://<command>/file:///<путь к JSON-файлу>

• cryptoarm:// - зарегистрированный протокол
• <command> - выполняемая команда
• <URI> - путь к файлу JSON с параметрами, нужными для выполнения команды

Вариант 2 (JSON встроенный):

cryptoarm://<command>/<JSON>

• cryptoarm:// - зарегистрированный протокол
• <command> - выполняемая команда
• <JSON> - JSON-RPC объект с параметрами, нужными для выполнения команды

JSON должен начинаться с {"jsonrpc":"2.0"...}.

Дополнительные параметры локального JSON:

Аутентификация#

КриптоАРМ поддерживает несколько механизмов аутентификации, которые могут быть указаны в параметре authType.

mTLS (авторизация по сертификату сервера)#

При вызове cryptoarm://<command>/<URL>/?id=<id>&authType=mtls КриптоАРМ:

1. Запрашивает серверный сертификат с <URL>.
2. Сравнивает его с сохранённым сертификатом доверенного сервиса.
3. Если сертификаты совпадают — доступ разрешён автоматически.
4. Если нет — отображает диалог подтверждения для пользователя.

OIDC (OpenID Connect)#

При вызове cryptoarm://<command>/<URL>/?id=<id>&authType=oidc КриптоАРМ:

1. Запрашивает параметры авторизации с сервера (эндпоинт authorization.parameters).
2. Строит URL авторизации и открывает браузер пользователя.
3. После успешной аутентификации получает токен доступа через callback.
4. Сохраняет токены в доверенном сервисе и использует их для последующих запросов (передаёт в заголовке Authorization: Bearer <token> или в query-параметре, в зависимости от настройки customAuth).

Комбинированная (oidc:mtls)#

При authType=oidc:mtls КриптоАРМ сначала выполняет OIDC-авторизацию, а затем использует клиентский сертификат (mTLS) для защищённых запросов.

Токен авторизации (customAuth)#

После успешной авторизации токен доступа автоматически добавляется ко всем последующим запросам к серверу в соответствии с настройками customAuth:

• in: "header" (по умолчанию) — токен в заголовке Authorization: Bearer <token>
• in: "query" — токен в query-параметре ?token=<token>
• in: "body" — токен в теле запроса как поле token

Название ключа, схема и размещение токена могут быть переопределены через customAuth.key и customAuth.scheme.

Описание запросов и ответов#

Все запросы между КриптоАРМ и сервером ДОЛЖНЫ соответствовать спецификации протокола JSON-RPC 2.0.

В качестве транспорта используется HTTP. Должен использоваться TLS, незащищенные соединения КриптоАРМ отклоняет.

При включенной настройке «Использовать только набор алгоритмов ГОСТ для подключений по API» КриптоАРМ будет принимать только ГОСТ TLS, остальные шифросюиты будут отклоняться.

POST-запрос#

КриптоАРМ выполняет HTTP POST-запросы, которые содержат заголовки:

• Content-Type: должен быть application/json.
• Content-Length: должен содержать правильную длину в соответствии с HTTP-спецификацией.
• Accept: должен быть application/json.

GET-запрос#

Используются для скачивания файлов с сервера (например, документов для подписи, вложений почты). Заголовки GET-запросов аналогичны POST, но без Content-Type и Content-Length.

Ответ#

HTTP-ответ сервера должен содержать заголовки:

• Content-Type: должен быть application/json.
• Content-Length: должен содержать правильную длину в соответствии с HTTP-спецификацией.

Объект Error#

В случае ошибки сервер должен отправить ответ следующей структуры:

HTTP-коды#