Транспорт и доверие#

Приложение выступает HTTP-клиентом: оно само обращается к сервису за параметрами и само отправляет результат. Локального сервера, принимающего входящие соединения, у него нет.

Содержание:

Сетевой вызов
Доверенный сервис
Профиль сервиса и настройки операции
Адреса файлов и токен
Локальный вызов
Подтверждение пользователем
Смотрите также

Сетевой вызов#

Формат ссылки:

cryptoarm://<command>/<https-url>

Адрес должен содержать ровно один непустой параметр id — идентификатор всей транзакции. Он используется в запросе параметров, в ответе сервиса и в результате операции.

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

После подтверждения доверия приложение сообщает сервису, что вызов получен:

{
  "jsonrpc": "2.0",
  "method": "diagnostics.callback",
  "id": "tx-42",
  "params": {
    "status": "Received",
    "VERSIONS": { "cryptoarm": "7.0.0" }
  }
}

Имя команды в методе записывается в нижнем регистре — например, signandencrypt.callback. Ответ на уведомление не требуется, и его доставка на выполнение команды не влияет.

Одновременно приложение отправляет запрос параметров:

{
  "jsonrpc": "2.0",
  "method": "diagnostics.parameters",
  "id": "tx-42",
  "diagnostic": {}
}

Для остальных команд поле diagnostic содержит VERSIONS, PROVIDERS и LICENSES.

Сервис отвечает параметрами команды:

{
  "jsonrpc": "2.0",
  "id": "tx-42",
  "result": {
    "operation": ["VERSIONS", "LICENSES"]
  }
}

Требования к ответу перечислены в разделе Описание запросов и ответов. Оформление видимого штампа PAdES проверяется менее строго, чем остальные поля: неизвестные поля игнорируются, а непригодные декоративные значения — цвет, логотип, масштаб — заменяются оформлением по умолчанию.

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

Доверенный сервис#

Сетевой вызов работает только по HTTPS; имя пользователя и пароль в адресе запрещены. При первом обращении с нового адреса приложение показывает сертификат сервиса и предлагает отменить вызов или сохранить сервис как доверенный. Об отмене сервис узнаёт из сообщения со статусом Canceled — см. Ошибки и отмена.

Доверие определяется тремя значениями:

точный адрес ресурса — схема, узел и порт;
отпечаток SHA-256 открытого ключа сертификата (SPKI pin);
отпечаток самого сертификата.

Обычная проверка цепочки TLS и имени узла сохраняется, а закреплённый ключ дополнительно проверяется при каждом запросе к сервису. Смена сертификата требует нового решения пользователя.

В окне согласия сертификат дополнительно проверяется по хранилищу сертификатов приложения: цепочка, срок действия, пригодность сертификата для TLS-сервера и соответствие имени узла. Результат этой проверки показывается пользователю вместе со сведениями о сертификате и цепочке.

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

Профиль сервиса и настройки операции#

Вместе с доверием создаётся отдельный профиль подписи для этого сервиса. Итоговые настройки операции вычисляются в порядке:

Значения по умолчанию, заданные приложением.
Профиль сервиса.
Явные параметры вызова.
Изменения пользователя в незаблокированных полях.

Профиль, с которым пользователь работал в последний раз вручную, не используется. Из профиля сервиса не переносятся состав операций, локальная выходная папка, удаление исходных файлов, МЧД и назначение результата: они задаются транзакцией API.

Адреса файлов и токен#

Адреса входных файлов и адрес получателя результата проверяются отдельно от адреса вызова. Новый адрес требует собственного подтверждения доверия.

Перенаправления (HTTP 3xx) выполняются только по HTTPS и только на серверы с тем же ключом, что у исходного адреса. Переход на сервер с другим ключом — например, в хранилище S3 — завершается ошибкой.

Значение extra.token добавляется как параметр accessToken к адресу получателя результата — на любом ресурсе, который прошёл проверку доверия. К адресу входного файла токен добавляется, только если файл на том же ресурсе, что и сам вызов. Для файлов на другом ресурсе используйте предподписанные ссылки либо передайте нужный параметр доступа прямо в адресе файла.

Службы штампов времени (TSP) и проверки статуса сертификата (OCSP) — исключение: к ним обращается не приложение, а криптографический провайдер. Принимается корректный адрес HTTP или HTTPS; ocspURL требует tspURL. Оба адреса показываются пользователю в окне подтверждения операции.

Локальный вызов#

Вместо адреса HTTPS ссылка может содержать JSON-конверт или адрес file:// файла с параметрами:

cryptoarm://startView/{"jsonrpc":"2.0","id":"tx-42","result":{"uiView":"SIGN_AND_ENCRYPT"}}
cryptoarm://signAndEncrypt/file:///C:/work/request.json

Конверт имеет вид { "jsonrpc": "2.0", "id": ..., "result": ... }. Если id не задан, приложение присваивает вызову случайный идентификатор, и он же попадает в имя файла результата. Входные файлы задаются адресами file:// или обычными абсолютными путями. Ссылку можно передать и в процентной кодировке — правило описано в разделе Кодирование ссылки.

Каталог результата задаётся обычным путём или адресом file://:

Команда	Где указывается
`signAndEncrypt`	`props.localResultParams.savePath`
`certificates`	`localResultParams` рядом с `operation` и `props`
`certrequests` и `diagnostics`	Рядом с `operation` и `props` либо внутри `props`

Для локального вызова signAndEncrypt и certrequests в props.uploader принимается адрес file://, обычный путь к каталогу или адрес HTTPS. Значение saveResultsSeparately: true создаёт отдельный файл результата для каждого идентификатора файла. Каталог может ещё не существовать — приложение создаст его после подтверждения вызова.

Если локальный вызов завершился ошибкой или пользователь отказал в разрешении, в тот же каталог записывается direct-result-<id>.json (для проверки подписи — verify-result-<id>.json) со статусом Canceled и причиной в ErrorDescription. Если каталог в параметрах не указан или параметры не читаются, файл не создаётся.

⚠️ Важно: сетевой вызов не может записать результат в локальный путь или в file://. Разрешение «Разрешить локальные вызовы до выхода» действует только до завершения работы приложения и не сохраняется.

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

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

Фоновая диагностика и фоновая проверка подписи разрешаются отдельными настройками доверенного сервиса, выключенными по умолчанию. Фоновая проверка действует только для одиночной операции VERIFYSIGN.

ПИН-код и временная лицензия из props.license хранятся только в памяти одной операции: в журнал и в лог они не попадают.

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

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