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

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

Это руководство описывает протокол cryptoarm://, доступные команды, форматы запросов и ответов и сценарии интеграции.

Содержание:

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

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

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

Возможны две точки вызова:

• сетевой вызов — параметры операции приложение запрашивает у сервиса по HTTPS, результат отправляет ему же;
• локальный вызов — параметры приходят прямо в ссылке или в файле на этом же компьютере, результат сохраняется в указанный каталог.

API работает с сертификатами X.509. Операции OpenPGP через него недоступны — для их автоматизации используйте командную строку.

📌 Примечание: криптографические операции требуют действующей лицензии на КриптоАРМ. Временную лицензию на одну операцию можно передать в параметре props.license.

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

Имя команды в ссылке нечувствительно к регистру.

Сценарий вызова из веб-приложения#

1. Инициация операции. Пользователь выбирает на портале документы и действие — например, подпись.
2. Формирование ссылки. Портал отображает ссылку cryptoarm:// с идентификатором транзакции или перенаправляет на неё браузер.
3. Запуск приложения. Система запускает КриптоАРМ, если он ещё не запущен, и передаёт ему ссылку.
4. Проверка сервиса. При первом обращении с этого адреса приложение показывает сертификат сервиса и запрашивает разрешение — см. Запрос от сетевого сервиса.
5. Запрос параметров. Приложение сообщает сервису о получении вызова уведомлением <команда>.callback и отправляет на указанный адрес JSON-RPC запрос <команда>.parameters, чтобы получить параметры операции.
6. Подготовка операции. Приложение загружает нужные файлы и открывает экран операции с переданными настройками.
7. Подтверждение пользователем. Пользователь проверяет, что именно запрошено, и запускает операцию.
8. Отправка результата. Результат уходит на адрес из props.uploader — в JSON или в multipart/form-data. Без этого адреса результат остаётся у пользователя.

Сценарий вызова из локального приложения#

1. Инициация операции. Пользователь выбирает файлы и действие в стороннем приложении.
2. Формирование запроса. Приложение готовит JSON-RPC объект с параметрами и открывает ссылку cryptoarm:// со встроенным JSON либо со ссылкой на файл параметров.
3. Запуск приложения. Система запускает КриптоАРМ, если он ещё не запущен.
4. Разрешение вызова. Приложение показывает окно «Разрешить локальный API-вызов?».
5. Подтверждение пользователем. Пользователь проверяет параметры операции и запускает её.
6. Сохранение результата. Результат сохраняется в каталог, указанный в параметрах операции.

Формат ссылки для сетевого вызова#

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

• cryptoarm:// — зарегистрированный протокол;
• <command> — выполняемая команда;
• <URL> — адрес, по которому приложение запросит параметры операции и на который отправит результат;
• id=<id> — обязательный параметр. Идентификатор транзакции.

Пример сетевого вызова:

cryptoarm://signAndEncrypt/https://api.example.ru/cryptoarm/json?id=tx-42

Требования к адресу:

• только HTTPS: незащищённые соединения приложение отклоняет;
• ровно один непустой параметр id;
• имя пользователя и пароль в адресе не допускаются.

Формат ссылки для локального вызова#

Вариант 1 — JSON в ссылке:

cryptoarm://<command>/<JSON>

Конверт приложение отличает от адреса по первому символу: значение, начинающееся с {, читается как JSON. Порядок ключей внутри конверта не важен. Объём встроенного JSON ограничен 64 МиБ. Состав result зависит от команды и описан на её странице.

cryptoarm://startView/{"jsonrpc":"2.0","id":"tx-42","result":{"uiView":"SIGN_AND_ENCRYPT"}}

Вариант 2 — файл параметров:

cryptoarm://<command>/file:///C:/work/request.json

Путь к файлу указывается в форме file://; сетевые узлы в таком адресе не поддерживаются. Входные файлы локального вызова задаются через file:// или обычным абсолютным путём.

Дополнительные поля конверта в ссылке:

Приложение показывает эти значения пользователю, но не проверяет их: решение принимает пользователь. Оба поля читаются только из конверта в ссылке: для варианта 2 разрешение запрашивается до чтения файла параметров, поэтому в окне показывается путь к файлу.

⚠️ Важно: сетевой вызов не может записать результат в локальный путь. Каталог результата задаётся только для локального вызова.

Кодирование ссылки#

Хвост ссылки — адрес или JSON — передаётся либо как есть, либо целиком в процентной кодировке (encodeURIComponent). Приложение принимает оба вида:

cryptoarm://signAndEncrypt/https://api.example.ru/cryptoarm/json?id=tx-42
cryptoarm://signAndEncrypt/https%3A%2F%2Fapi.example.ru%2Fcryptoarm%2Fjson%3Fid%3Dtx-42

В командной строке кавычки обязательны: без них пробелы и & разорвут ссылку на несколько аргументов, и приложение получит только её начало.

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

Подлинность сервиса подтверждается сертификатом ресурса, который пользователь видит и принимает при первом обращении, и проверкой этого сертификата при каждом запросе. Подробности — в разделе Транспорт и доверие. Аутентификация пользователя — отдельный механизм, и включает её сам сервис.

authType=oidc#

Сервису, которому нужен вошедший пользователь, достаточно добавить в ссылку authType=oidc:

cryptoarm://signAndEncrypt/https://api.example.ru/cryptoarm/json?id=tx-42&authType=oidc

Дальше приложение:

1. запрашивает у сервиса параметры входа — {"jsonrpc": "2.0", "method": "authorization.parameters", "id": "<id>"};
2. ожидает в ответе params.authorizationParams с полями issuer и clientId (необязательный массив scopes или строка scope через пробел, по умолчанию openid offline_access), params.nextUrl и необязательный params.customAuth;
3. выполняет вход в указанный провайдер: Authorization Code с PKCE, системный браузер, возврат на cryptoarm://callback/. Вход принадлежит сетевому профилю этого же ресурса: если профиля ещё нет, он создаётся по authorizationParams, а серверы лицензий и документов берутся из /.well-known/service-resources ресурса, когда тот их публикует; уже выполненный вход используется повторно и продлевается по refresh-токену без вопросов к пользователю;
4. повторяет исходную команду по адресу nextUrl, добавляя токен в заголовок. Токен — id_token провайдера, не access_token: сервис проверяет его подпись по JWKS провайдера.

Если сервис отвечает 401 на запрос с токеном, приложение считает токен отозванным: профиль переходит в состояние «требуется вход», пользователь входит заново, и команда повторяется один раз с новым токеном. Второй 401 — уже отказ вызова. 403 входом не лечится и повторов не вызывает.

nextUrl обязан оставаться на том же origin, что и исходный вызов: токен не уходит на другой хост. customAuth задаёт только имя заголовка и схему ({"in": "header", "headerName": "Authorization", "scheme": "bearer"} — значения по умолчанию; вместо headerName принимается и key). Передача токена в query или в теле запроса не поддерживается. Тот же заголовок добавляется к загрузке входных файлов и к отправке результата, если они идут на этот же origin.

Другие значения authType — включая mtls и oidc:mtls — отклоняются ещё при разборе ссылки, до подтверждения доверия к сервису: приложение не обращается к нему, сообщения об ошибке сервис не получает, а код UNSUPPORTED_AUTH_TYPE остаётся только в лог-файле. Локальный вызов (JSON или файл параметров) с authType отклоняется так же: аутентифицироваться там не к кому.

Токен доступа к файлам#

Токен доступа к файлам передаётся в extra.token команды signAndEncrypt и добавляется только к загрузке с адреса исходного вызова.

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

Все запросы между приложением и сервисом соответствуют спецификации JSON-RPC 2.0. Транспорт — HTTP поверх TLS.

POST-запрос#

Приложение выполняет POST-запросы с заголовками:

• Content-Type: application/json; charset=utf-8;
• Content-Length — длина тела запроса;
• Accept: application/json.

GET-запрос#

GET-запросы используются для загрузки файлов — например, документов для подписи. Своих заголовков приложение к ним не добавляет; токен доступа передаётся параметром accessToken в адресе файла.

Перенаправления выполняются в пределах серверов с тем же ключом — см. Адреса файлов и токен.

Запрос параметров#

Для самой команды diagnostics поле diagnostic — пустой объект: сведения о рабочем месте не передаются до того, как пользователь разрешит операцию.

Ответ с параметрами#

В теле ответа сервис возвращает конверт JSON-RPC. Заголовки ответа приложение не проверяет и разбирает тело как JSON:

Правила разбора конверта:

• параметры берутся из result; params принимается для совместимости, если result нет;
• jsonrpc равен "2.0"; id совпадает с идентификатором из ссылки, id другой транзакции отклоняется;
• объект в error — ответ с ошибкой;
• поле со значением null на любой глубине считается отсутствующим;
• пакетные (batch) запросы и скалярные значения вместо объекта не принимаются;
• неизвестные значения перечислимых полей и недопустимые сочетания операций отклоняются, а не заменяются значениями по умолчанию.

Объект Error#

Если параметры выдать нельзя, сервис отвечает объектом ошибки:

Ответ на результат#

Результат операции приложение отправляет как уведомление JSON-RPC. Сервис может ответить любым кодом 2xx, включая 204 No Content; тело ответа не требуется.

HTTP-коды#

Смотрите также#

• Приложение и пользователь — окна согласия на стороне пользователя.
• Транспорт и доверие — HTTPS, доверенные сервисы, локальный вызов.
• Лимиты, статусы и ошибки — ограничения и завершение операции.
• Выполнение операций в командной строке — другой способ автоматизации.