Команда signAndEncrypt#

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

Содержание:

• Общая информация
• Формат ссылки
• Операции
• Получение параметров операции
• Файлы
• Параметры операции
• Параметры extra
• Сертификаты
• Подпись PDF и штамп
• Машиночитаемая доверенность
• Настройки и подтверждение
• Отправка результатов
• Справочник полей результата
• Смотрите также

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

Команда работает с сертификатами X.509. Операции OpenPGP через внешний API недоступны.

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

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

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

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

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

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

Операции#

Поле operation — непустой массив без повторов:

Прямые операции (можно комбинировать):

Обратные операции (выполняются по одной):

Проверка подписи:

Ограничения:

• прямые и обратные операции не смешиваются;
• VERIFYSIGN и UNSIGN выполняются только по одной;
• отдельной операции UNZIP нет: ZIP-слой снимается вместе с проверкой или расшифрованием.

Получение параметров операции#

Формат запроса#

Получив команду, приложение отправляет на указанный адрес запрос параметров.

{
  "jsonrpc": "2.0",
  "method": "signAndEncrypt.parameters",
  "id": "tx-42",
  "diagnostic": {
    "VERSIONS": { "csp": "5.0.13000", "cryptoarm": "1.2.0", "openssl": "3.0.13" },
    "PROVIDERS": { "GOST2012_256": true, "GOST2012_512": true, "openssl": true },
    "LICENSES": {
      "csp": { "status": true, "type": "client", "expiration": "" },
      "cryptoarm": { "status": true, "type": "Permanent", "expiration": "" }
    }
  }
}

Формат ответа#

Пример для прямых операций:

{
  "jsonrpc": "2.0",
  "id": "tx-42",
  "result": {
    "operation": ["SIGN", "ENCRYPT"],
    "props": {
      "headerText": "Подписание документов",
      "descriptionText": "Пакет документов на согласование",
      "files": [
        {
          "id": "document-1",
          "name": "document.pdf",
          "url": "https://api.example.ru/files/document.pdf"
        }
      ],
      "uploader": "https://api.example.ru/cryptoarm/result",
      "uploadMethod": "json",
      "extra": {
        "signType": 0,
        "signStandard": "cades-bes",
        "encryptAlgorithm": 0,
        "returnFiles": true
      }
    }
  }
}

Пример для проверки подписи:

{
  "jsonrpc": "2.0",
  "id": "tx-42",
  "result": {
    "operation": ["VERIFYSIGN"],
    "props": {
      "files": [
        {
          "id": "signature-1",
          "name": "document.pdf.sig",
          "url": "https://api.example.ru/files/document.pdf.sig",
          "urlDetached": "https://api.example.ru/files/document.pdf"
        }
      ],
      "uploader": "https://api.example.ru/cryptoarm/result",
      "extra": { "printReport": true }
    }
  }
}

Файлы#

Файл описывается объектом:

Числовой id принимается и возвращается строкой.

Поля props.files и props.archive взаимоисключающие. В archive передаётся ZIP с входными файлами: он распаковывается до запуска операции. Результат прямой операции над archive упаковывается в ZIP, как при ARCHIVE. Идентификаторы файлов должны быть уникальны.

Если хотя бы один файл не удалось получить, вызов завершается до открытия экрана операции, и остальные файлы не обрабатываются. Сервис получает сообщение об отмене, где ErrorDescription называет файл: Input file document-2 cannot be used: ….

Для прямых операций (SIGN, ARCHIVE, ENCRYPT) оба поля можно не передавать: тогда экран операции открывается пустым, и файлы добавляет сам пользователь. Каждый добавленный файл получает новый идентификатор, и в результате приходит именно он: сопоставить результат с файлом сервиса в этом режиме нельзя. Для проверки подписи, расшифрования и снятия подписи файлы обязательны.

Параметры операции#

Параметры extra#

Числовые значения принимаются и строками: "1" равнозначно 1.

Неизвестное значение перечислимого поля — ошибка: приложение не заменяет его значением по умолчанию.

Сертификаты#

Сертификат подписанта задаётся одним из трёх способов:

{
  "extra": {
    "signCertificate": { "hash": "b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9" }
  }
}

Если сертификата подписанта нет в хранилище пользователя, у него нет закрытого ключа или это не сертификат ГОСТ, операция не отклоняется: пользователь выбирает сертификат подписи сам.

Получатели шифрования передаются в encryptCertificates — массивом сертификатов в формате DER, закодированном в Base64. Устанавливать их пользователю не нужно: они используются в том виде, в котором их передал сервис, и в хранилище не добавляются. Сертификат УЦ получателем быть не может. Строка, которая не является сертификатом, и повторяющиеся сертификаты отклоняются.

Получатель может быть сертификатом ГОСТ или сертификатом с ключом другого алгоритма, например RSA. Если encryptAlgorithm не задан, алгоритм выбирается по ключам получателей: для ГОСТ — ГОСТ 28147-89 или алгоритм из профиля доверенного сервиса, для остальных — AES-256. Алгоритмы encryptAlgorithm относятся к ГОСТ, поэтому зашифровать с ними для получателя с ключом RSA нельзя.

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

Подпись PDF и штамп#

Оформление видимого штампа задаётся объектом PAdESStampAppearance — для подписи PAdES — и объектом signStampAppearance — для отдельной печатной копии со штампом.

Блок mockupSettings — вид штампа:

Блок requisitesSettings — состав реквизитов:

Элемент списка реквизитов: { "dataKey": "…", "isEnabled": true, "editedValue": "…", "title": "…" }. Отключённые и повторяющиеся реквизиты отбрасываются. Доступные значения dataKey: serialNumber, validityTimeSpan, subjectFriendlyName, individual, jobPosition, issuerFriendlyName, organizationName, mark, description, location, signingTime, MCHDNumber, hash, signatureAlgorithm.

Размещение штампа для PAdES задаётся объектом signStampPAdES:

Для печатной копии страницы задаются внутри signStampAppearance: pageSelection и строка pageNumbers вида "1,3-5".

Устаревший способ размещения signStampPosition с полями width, height, horizontalPadding и verticalPadding также принимается; его значения задаются в миллиметрах, тогда как размеры в signStampPAdES — в пунктах PDF. По умолчанию штамп имеет размер 102,3 × 39,16 мм и отступы 66,6 мм по горизонтали и 20 мм по вертикали.

Недопустимые размеры, выбор страниц, поворот и размещение возвращают ошибку и не заменяются значениями по умолчанию. Значения по умолчанию подставляются только для декоративных полей — цвета, логотипа и масштаба.

Машиночитаемая доверенность#

МЧД передаётся в extra.MCHD вместе с отсоединёнными подписями:

{
  "MCHD": {
    "xml": {
      "id": "mchd",
      "name": "power.xml",
      "url": "https://api.example.ru/files/power.xml"
    },
    "signatures": [
      {
        "id": "mchd-sign",
        "name": "power.xml.sig",
        "url": "https://api.example.ru/files/power.xml.sig"
      }
    ]
  }
}

Требуется файл XML и хотя бы одна подпись; идентификаторы всех файлов МЧД должны быть уникальны.

Настройки и подтверждение#

Явно переданные через API тип и стандарт подписи, кодировки, расширения файлов, алгоритм шифрования, параметры PAdES и МЧД и сертификаты заблокированы для изменения. Если параметр не передан, начальное значение берётся из профиля сервиса, и пользователь может его изменить.

Состав операций, входные файлы и назначение результата задаются транзакцией API и не редактируются. Значение showSettingsBeforeOperation: false пропускает экран настроек, но не подтверждение запуска.

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

Прямые и обратные операции#

Результат отправляется методом signAndEncrypt.outDirectResults.

{
  "jsonrpc": "2.0",
  "method": "signAndEncrypt.outDirectResults",
  "params": {
    "id": "tx-42",
    "status": "Completed",
    "directResults": [
      {
        "id": "document-1",
        "out": "<Base64>",
        "signValid": true,
        "signers": [
          {
            "isValid": true,
            "signingTime": 1594209848000,
            "isDetached": true,
            "signerCertificate": {
              "hash": "b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9",
              "subjectName": "CN=Example User",
              "status": true
            }
          }
        ]
      }
    ]
  }
}

После подписи приложение проверяет получившуюся подпись и возвращает её сведения в полях signValid и signers — в том же виде, что и при проверке подписи. Результат SIGN вместе с ENCRYPT не проверяется: он зашифрован для получателя. Если проверка не выполнилась, результат отправляется без этих полей; недействительная по итогам проверки подпись результат не отменяет.

Необработанные файлы#

Если подпись, шифрование, архивирование, расшифрование или снятие подписи не выполнены хотя бы для одного файла, результаты на uploader не отправляются. Так сервис не получит пустой файл вместо необработанного.

Вместо результатов сервис получает сообщение об отмене на адрес, с которого получены параметры:

{
  "jsonrpc": "2.0",
  "method": "signAndEncrypt.outDirectResults",
  "id": "tx-42",
  "params": {
    "status": "Canceled",
    "Error": true,
    "ErrorDescription": "Operation failed for files: document-2 (x509.sign.failed)"
  }
}

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

Проверка подписи#

Результат проверки отправляется методом signAndEncrypt.verifySignResults в поле verifySignResults. Содержимое файлов при проверке не возвращается: вместо него передаются сведения о подписи, а при printReport: true — PDF-отчёт в поле outReport.

{
  "jsonrpc": "2.0",
  "method": "signAndEncrypt.verifySignResults",
  "params": {
    "id": "tx-42",
    "status": "Completed",
    "verifySignResults": [
      {
        "id": "signature-1",
        "signValid": false,
        "isSignaturePades": false,
        "signers": [
          {
            "isValid": false,
            "isDetached": true,
            "isCades": true,
            "cadesType": 1,
            "signingTime": 1594209848000,
            "signatureAlgorithm": "1.2.643.7.1.1.3.2",
            "signatureDigestAlgorithm": "1.2.643.7.1.1.2.2",
            "signerCertificate": {
              "hash": "b0a1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9",
              "issuerFriendlyName": "Example CA",
              "issuerName": "CN=Example CA",
              "subjectFriendlyName": "Example User",
              "subjectName": "CN=Example User",
              "status": true,
              "serial": "01AB",
              "notBefore": 1593603200000,
              "notAfter": 1725139200000
            }
          }
        ]
      }
    ]
  }
}

💡 Примечание: недействительная подпись — это результат проверки, а не ошибка. Конверт имеет status: "Completed", а signValid и signers[].isValid — значение false.

Передача файлов#

При uploadMethod: "json" и returnFiles: true содержимое файлов передаётся в поле out в Base64. Base64 увеличивает объём передачи примерно на треть, поэтому для больших результатов используйте multipart/form-data или returnFiles: false.

При uploadMethod: "multipart/form-data" конверт JSON передаётся в поле operation-response, а файлы — отдельными частями, имя каждой части равно идентификатору исходного файла. Отчёт о проверке и печатная копия со штампом остаются полями конверта в Base64.

Значение returnFiles: false оставляет метаданные результата без содержимого файлов.

Сохранение результата локально#

Для локального вызова файлы результата — подписанные, зашифрованные, расшифрованные — сохраняются на диск:

• в каталог из props.uploader (file:// или обычный путь), если он задан;
• иначе — рядом с исходными файлами, для архива — рядом с архивом.

Файл JSON с результатом записывается в тот же каталог props.uploader либо в каталог props.localResultParams.savePath. Содержимого файлов в нём нет — поля out, outSignStamp и outReport не передаются, а файлы берутся с диска; name называет файл результата. Имена файлов JSON:

При saveResultsSeparately: true для каждого входного файла создаётся отдельный файл direct-result-<id>-<fileId>.json. Существующие файлы не перезаписываются: к имени добавляется порядковый номер.

Без получателя результата#

Если задан props.uploader, после успешной отправки результата вкладка операции закрывается; исключение — VERIFYSIGN, результат проверки остаётся на экране.

Если не заданы ни props.uploader, ни props.localResultParams.savePath, результат никуда не отправляется и остаётся у пользователя: экран операции открывается как обычно, а после завершения вкладка не закрывается. Сервис в этом режиме не получает ни результата, ни уведомления об успехе. Об ошибке сообщение уходит, как обычно, — см. Ошибки и отмена.

Справочник полей результата#

Объект результата файла#

Статус подписанта#

Сертификат подписанта#

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

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