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

• Общая информация
• Доступные команды
• Cценарий выполнения команд (для взаимодействия с web-приложениями)
• Cценарий выполнения команд (для взаимодействия с локальным приложением)
• Формат ссылки для web КриптоАРМ API
• Формат ссылки для локального варианта КриптоАРМ API
• Описание запросов и ответов

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

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

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

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

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

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

Cценарий выполнения команд (для взаимодействия с web-приложениями)#

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

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

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

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

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

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

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

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

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

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

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

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

Cценарий выполнения команд (для взаимодействия с локальным приложением)#

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

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

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

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

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

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

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

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

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

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

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

cryptoarm://<command>/<URL>/?id=<id>

• cryptoarm:// - зарегистрированный протокол

• <command> - выполняемая команда

• <URL> - ссылка на получение JSON с параметрами, нужными для выполнения команды

• ?id=<id> - обязательный параметр. Идентификатор транзакции.

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

Вариант 1:

cryptoarm://<command>/<URI>

• cryptoarm:// - зарегистрированный протокол

• <command> - выполняемая команда

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

Вариант 2:

cryptoarm://<command>/<JSON>

• cryptoarm:// - зарегистрированный протокол

• <command> - выполняемая команда

• <JSON> - JSON с параметрами, нужными для выполнения команды

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

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

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

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

POST-запрос

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

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

GET-запрос

Не используются.

Ответ

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

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

Объект Error

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

HTTP-коды