Перейти к содержанию

Команда signAndEncrypt — описание и примеры#

Команда signAndEncrypt API КриптоАРМ предназначена для подписи, шифрования и проверки документов при интеграции с внешними системами. Она позволяет безопасно обрабатывать одиночные файлы и пакеты документов через JSON-RPC, поддерживает различные режимы операций и может использоваться как механизм аутентификации.

Содержание:


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

Команда signAndEncrypt (подпись и шифрование) используется для запроса на подпись документа или пакета документов. Может использоваться в качестве аутентификатора.

📌 Выполнение операции требует действующей лицензии на КриптоАРМ.

Схема работы команды signAndEncrypt


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

Для выполнения команды signAndEncrypt должна быть сформирована ссылка вида:

cryptoarm://signAndEncrypt/<URL>/?id=<id>[&authType=<authType>]
  • cryptoarm:// - зарегистрированный протокол
  • signAndEncrypt - выполняемая команда
  • <URL> - ссылка на получение JSON с параметрами, нужными для выполнения команды
  • ?id=<id> - обязательный параметр. Идентификатор транзакции.
  • &authType=<authType> - необязательный параметр. Тип аутентификации.

Пример:

cryptoarm://signAndEncrypt/https://example.com/json?id=2c48eb32-a0a8-405c-ade9-eed130605cba

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

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

🔍 Общее описание указано в разделе Формат ссылки.


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

После получения команды signAndEncrypt КриптоАРМ отправляет запрос на <URL> для получения параметров операции.

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

Ключ Значение Описание
jsonrpc «2.0» Версия JSON-RPC протокола. Всегда «2.0».
method signAndEncrypt.parameters Используемый метод. Всегда signAndEncrypt.parameters.
id Уникальный идентификатор Используется идентификатор, который указан в ссылке на операцию.
diagnostic IDiagnosticsInformation Диагностическая информация о рабочем месте. Содержит поля VERSIONS, PROVIDERS, LICENSES.

Пример:

Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "signAndEncrypt.parameters",
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
    "diagnostic": {
      "VERSIONS": {
        "csp": "5.0.11753",
        "cryptoarm": "2.5.2",
        "openssl": "1.1.1w"
      },
      "PROVIDERS": {
        "GOST2012_256": true,
        "GOST2012_512": true,
        "openssl": true
      },
      "LICENSES": {
        "csp": {
          "status": true,
          "type": "",
          "expiration": ""
        },
        "cryptoarm": {
          "status": true,
          "type": "Permanent",
          "expiration": ""
        }
      }
    }
}

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

Ключ Значение Описание
jsonrpc «2.0» Версия JSON-RPC протокола. Всегда «2.0».
result ISignAndEncryptParameters Объект со сведениями о параметрах операции подписи
id Уникальный идентификатор Используется идентификатор, который указан в ссылке на операцию.

Пример для прямых операций (SIGN + ARCHIVE + ENCRYPT):

HTTP/1.1 200 OK
Connection: close
Content-Length: ...
Content-Type: application/json
Date: Sat, 08 Jul 2020 12:04:08 GMT
{
    "jsonrpc": "2.0",
    "result": {
        "operation": [
            "SIGN",
            "ARCHIVE",
            "ENCRYPT"
        ],
        "props": {
            "headerText": "Подпись документов cryptoarm.ru",
            "descriptionText": "Подпись пакета документов",
            "license": "",
            "files": [{
                    "name": "file1.txt",
                    "url": "http://localhost:8080/public/files/file1.txt",
                    "id": "1",
                    "urlDetached": ""
                },
                {
                    "name": "file2.txt",
                    "url": "http://localhost:8080/public/files/file2.txt",
                    "id": "2",
                    "urlDetached": ""
                },
                {
                    "name": "file4.pdf",
                    "url": "http://localhost:8080/public/files/file4.pdf",
                    "id": "4",
                    "urlDetached": ""
                }
            ],
            "uploader": "http://localhost:8080/upload",
            "uploadMethod": "json",
            "extra": {
                "token": "9c7101f7-9c47-4481-b4da-a6a497abde08",
                "signType": 1,
                "signStandard": 1,
                "signEncoding": 1,
                "encryptEncoding": 1,
                "encryptAlgorithm": 2,
                "returnFiles": true,
                "isAddStampToPdf": true
            }
        }
    },
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

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

HTTP/1.1 200 OK
Content-Type: application/json
{
    "jsonrpc": "2.0",
    "result": {
        "operation": ["VERIFYSIGN"],
        "props": {
            "files": [{
                "name": "signed_file.txt.sig",
                "url": "http://localhost:8080/public/files/signed_file.txt.sig",
                "id": "8",
                "urlDetached": "http://localhost:8080/public/files/original_file.txt"
            }],
            "extra": {
                "printReport": true
            }
        }
    },
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

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

Отправка результата прямых операций#

После того, как пользователь выберет нужные сертификаты, КриптоАРМ выполняет операцию. Результаты отправляются POST-запросом в формате JSON или multipart/form-data.

Вариант 1: JSON (по умолчанию, uploadMethod = "json")#

Файлы результатов кодируются в Base64 и передаются в теле JSON-запроса.

Ключ Значение Описание
jsonrpc «2.0» Версия JSON-RPC протокола. Всегда «2.0».
method signAndEncrypt.outDirectResults Используемый метод. Всегда signAndEncrypt.outDirectResults.
params Объект типа IDirectResults Сведения о результатах прямой операции
Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "signAndEncrypt.outDirectResults",
    "params": {
        "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
        "status": "Completed",
        "directResults": [
          {
            "id": "2",
            "out": "MIIWgQYJKoZIhvcNAQcCoIIWcjCCFm4CA…cN/aHmA=",
            "signValid": true,
            "signers": [
              {
                "isValid": true,
                "signingTime": 1594209848000,
                "isDetached": false,
                "signerCertificate": {
                  "hash": "abc123...",
                  "issuerFriendlyName": "УЦ Тест",
                  "issuerName": "CN=УЦ Тест",
                  "subjectFriendlyName": "Иванов Иван",
                  "subjectName": "CN=Иванов Иван",
                  "status": true,
                  "serial": "1234567890",
                  "notAfter": 1725139200000,
                  "notBefore": 1593603200000
                }
              }
            ]
          }
        ]
    }
}

Вариант 2: multipart/form-data (uploadMethod = "multipart/form-data")#

Файлы результатов передаются как бинарные вложения в multipart-запросе. JSON с метаданными — в поле operation-response.

При использовании multipart/form-data файлы передаются как есть (без Base64-кодирования). Заголовок Content-Type устанавливается автоматически (multipart/form-data).

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

Результаты проверки подписи отправляются POST-запросом.

Ключ Значение Описание
jsonrpc «2.0» Версия JSON-RPC протокола. Всегда «2.0».
method signAndEncrypt.verifySignResults Используемый метод.
params Объект типа IVerifySignResults Сведения о проверке подписи
Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "signAndEncrypt.verifySignResults",
    "params": {
        "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
        "status": "Completed",
        "verifySignResults": [
          {
            "id": "2",
            "signValid": false,
            "isSignaturePades": false,
            "signers": [
              {
                "isValid": false,
                "signingTime": 1594209848000,
                "isDetached": true,
                "isCades": true,
                "cadesType": 1,
                "signatureAlgorithm": "1.2.643.7.1.1.3.2",
                "signatureDigestAlgorithm": "1.2.643.7.1.1.2.2",
                "signerCertificate": {
                  "hash": "abc123...",
                  "issuerFriendlyName": "Минкомсвязь России",
                  "issuerName": "Минкомсвязь России",
                  "subjectFriendlyName": "Минкомсвязь России",
                  "subjectName": "Минкомсвязь России",
                  "status": true,
                  "serial": "12345",
                  "provider": "Crypto-Pro GOST R 34.10-2012",
                  "notAfter": 1725139200000,
                  "notBefore": 1593603200000,
                  "rootCAMinComSvyaz": true
                }
              }
            ],
            "outReport": "base64_encoded_pdf_report..."
          }
        ]
    }
}

Для операций VERIFYSIGN файлы результатов НЕ возвращаются (поле out всегда пустое). Вместо них передаются свойства подписи (signProps). Если включён printReport, в поле outReport может быть передан PDF-отчёт в Base64.

Обработка ошибок#

При частичном успехе (некоторые файлы обработаны успешно, некоторые — нет) отправляется ответ со status: "Error" и Error: true, с полем ErrorDescription, содержащим описание ошибки, и списком частичных результатов в directResults.

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

Если uploader содержит путь file://, результаты сохраняются локально:

  • file:///path/to/dir — для каждого файла создаётся JSON-файл с результатами (direct-result-{id}-{fileId}.json)
  • Через localResultParams.savePath — аналогично

Имя файла: <operation>-result-<id><-fileId>.json (например, direct-result-2c48eb32-1.json).


Справочник интерфейсов#

Интерфейс ISignAndEncryptParameters#

Объекты данного типа описывают вид операции и её параметры.

Свойство Тип Описание
operation string[] Тип операции. Доступные значения: SIGN, ARCHIVE, ENCRYPT, VERIFYSIGN, UNSIGN, UNZIP, DECRYPT. Нельзя смешивать прямые (SIGN, ARCHIVE, ENCRYPT) и обратные (UNSIGN, UNZIP, DECRYPT) операции. VERIFYSIGN не комбинируется с другими.
props ISignAndEncryptOperationProps Параметры операции

Типы операций#

Прямые операции (прямые):

Значение Описание
SIGN Подпись
ARCHIVE Архивирование
ENCRYPT Шифрование

Обратные операции:

Значение Описание
UNSIGN Снятие подписи
DECRYPT Расшифрование
UNZIP Разархивирование

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

Значение Описание
VERIFYSIGN Проверка подписи

Интерфейс ISignAndEncryptOperationProps#

Интерфейс ISignAndEncryptOperationProps описывает параметры операции.

Свойство Тип Описание
headerText? string Необязательный параметр. Используется для отображения в заголовке окна. Максимальная длина - 40 символов.
descriptionText? string Необязательный параметр. Используется для отображения в сведениях об операции. Максимальная длина - 120 символов.
license? string Необязательное свойство. Содержит временную лицензию, которая будет использоваться для выполнения операции в КриптоАРМ.
uploader string Ссылка, на которую будут отправлены или сохранены результаты операции. Поддерживает протоколы https:// и file://. Если указан file://, результаты сохраняются локально в указанную директорию.
uploadMethod? string Способ отправки результатов. Возможные значения: "json" (по умолчанию) — файлы в Base64 внутри JSON, "multipart/form-data" — файлы как бинарные вложения в multipart-запросе.
files Массив типа IFile[] Массив файлов на подпись. Если не передан, то должен быть передан параметр archive.
archive IFile Архив файлов на подпись. Распаковываются после получения. Параметр может использоваться вместо files.
extra Объект типа IExtra Настройки операции
localResultParams Объект типа ILocalResultParams Необязательное свойство. Используется только для локального API. Указывает пути для сохранения результатов.

Интерфейс IFile#

Интерфейс IFile описывает файлы и ссылки на них.

Свойство Тип Описание
name string Имя файла (с расширением)
url string Ссылка на скачивание файла
id string Уникальный идентификатор файла
urlDetached? string Необязательный параметр. Используется для откреплённой подписи — ссылка на файл с отделённой подписью.

Интерфейс IExtra#

Интерфейс IExtra описывает настройки операции.

Если параметр не задан, то пользователю доступен выбор из всех доступных в приложении значений.

Свойство Тип Описание
signType? number/string Необязательный параметр. Тип подписи. 0 — присоединённая, 1 — отсоединённая.
signStandard? number/string Необязательный параметр. Стандарт подписи. 0 — CAdES-BES (CMS), 1 — CAdES-X Long Type 1, 2 — CAdES-T, 3 — CAdES-A. Также поддерживается псевдоним signStandart.
signEncoding? number/string Необязательный параметр. Кодировка подписи: 0 — PEM (BASE-64), 1 — DER.
encryptEncoding? number/string Необязательный параметр. Кодировка шифрования: 0 — BASE-64, 1 — DER.
encryptAlgorithm? number Необязательный параметр. Алгоритм шифрования: 0 — ГОСТ 28147-89, 1 — ГОСТ 34.12-2015 Магма, 2 — ГОСТ 34.12-2015 Кузнечик.
timestampOnSign? string Необязательный параметр. Штамп времени на подпись ("true"/"false"). Если стандарт подписи не CAdES-BES, автоматически включается.
timestampOnData? string Необязательный параметр. Штамп времени на данные ("true"/"false").
tspURL? string Необязательный параметр. Адрес службы штампов времени.
ocspURL? string Необязательный параметр. Адрес службы актуальных статусов (OCSP).
token? string Необязательный параметр. Токен, который будет использоваться при скачивании файлов с сервиса (добавляется как query-параметр accessToken).
encryptCertificates? string[] Необязательный параметр. Массив сертификатов шифрования в формате X.509 Base64.
signCertificate? { x509: string } | { issuerName: string, serial: string } | { hash: string } Необязательный параметр. Сертификат подписчика: либо X.509 в Base64, либо параметры для поиска в хранилище (по issuerName+serial или по hash).
signatureExtension? string Необязательный параметр. Расширение для подписанного файла (например, "sig", "p7s"). По умолчанию: "sig".
encryptionExtension? string Необязательный параметр. Расширение для зашифрованного файла. По умолчанию: "enc".
isAddStampToPdf? boolean Необязательный параметр. Добавить штамп подписи для PDF-файлов.
isSignaturePades? boolean Необязательный параметр. Использовать формат подписи PAdES для PDF.
isPdfCertificationSign? boolean Необязательный параметр. Сертификационная подпись PDF.
signerChainIncludeKind? string Необязательный параметр. Тип включения цепочки сертификатов: "personal" (только подписчик) или "full" (вся цепочка). По умолчанию: "personal".
isSafeMode? boolean Необязательный параметр. Безопасный режим подписи.
printReport? boolean Необязательный параметр. Создавать PDF-отчёт о проверке подписи (только для VERIFYSIGN).
returnFiles? boolean Необязательный параметр. Возвращать ли файлы результатов. По умолчанию: true. Если false, в ответе передаются только метаданные без содержимого файлов.
showSettingsBeforeOperation? boolean Необязательный параметр. Показывать ли окно настроек перед выполнением операции. По умолчанию: true.
MCHD? object Необязательный параметр. Файл метки доверенного времени (МЧД).
signStampAppearance? ISignStampAppearance Необязательный параметр. Параметры внешнего вида штампа подписи.
PAdESStampAppearance? ISignStampAppearance Необязательный параметр. Параметры внешнего вида штампа PAdES.
signStampPAdES? { isDisplayedOnAllPages?: boolean, pageNumbers?: number[], pagesSelection?: PagesSelection, pdfMarkedArea?: IPdfMarkedArea } Необязательный параметр. Параметры размещения штампа PAdES.
signStampPosition? IPdfAreaDimensions Необязательный параметр. Позиция и размеры области штампа подписи.

Интерфейс IDirectResults#

Объекты данного типа описывают результаты прямой операции.

Свойство Тип Описание
id string Идентификатор транзакции.
status string Статус выполнения операции: "Completed" (успех) или "Error" (ошибка).
Error? boolean Необязательное поле. Присутствует при ошибке (true).
ErrorDescription? string Необязательное поле. Описание ошибки.
directResults IDirectResultOut[] Массив результатов прямых операций

Интерфейс IDirectResultOut#

Объекты данного типа содержат результаты прямой операции для файла.

Свойство Тип Описание
id string Идентификатор исходного файла.
out string Результат операции в BASE-64. Может быть пустой строкой при ошибке конкретного файла.
outReport? string Необязательный параметр. PDF-отчёт в Base64.
outSignStamp? string Необязательный параметр. PDF со штампом подписи в Base64 (если isAddStampToPdf).
signers? ISignerStatus[] Необязательный параметр. Сведения о подписчиках.
signValid? boolean Необязательный параметр. Общий статус всех подписей файла.
isSignaturePades? boolean Необязательный параметр. Является ли подпись PAdES.

Интерфейс IVerifySignResults#

Объекты данного типа описывают результаты проверки подписи.

Свойство Тип Описание
id string Идентификатор транзакции.
status string Статус: "Completed" или "Error".
Error? boolean Флаг ошибки.
ErrorDescription? string Описание ошибки.
verifySignResults IVerifySignResult[] Массив результатов проверки

Интерфейс IVerifySignResult#

Объекты данного типа описывают результат проверки подписи для одного файла.

Свойство Тип Описание
id string Идентификатор исходного файла
signValid boolean Общий статус проверки подписи
isSignaturePades boolean Является ли подпись формата PAdES
signers ISignerStatus[] Информация о подписчиках документа
outReport? string Необязательный параметр. PDF-отчёт в Base64 (если printReport: true).

Интерфейс ISignerStatus#

Объекты данного типа описывают сведения о подписчиках.

Свойство Тип Описание
signerCertificate ICertificateIdentityInfo Сведения о сертификате подписчика. Кроме полей из ICertificateIdentityInfo дополнительно содержит поля: hash, issuerFriendlyName, issuerName, subjectFriendlyName, subjectName, status, serial, notAfter (number), notBefore (number), rootCAMinComSvyaz (boolean), provider (string).
isValid boolean Статус подписи
signingTime number Время подписи (timestamp в миллисекундах)
isDetached boolean Признак отсоединённой подписи
isCades? boolean Признак CAdES подписи
cadesType? number Тип CAdES подписи
isSignaturePades? boolean Признак PAdES подписи
signatureAlgorithm? string OID алгоритма подписи
signatureDigestAlgorithm? string OID алгоритма хеширования
verifyingTime? number Время проверки (timestamp)
extVerifyInfo? any Дополнительная информация о проверке

Интерфейс ILocalResultParams#

Объекты данного типа используется только в параметрах локального API.

Свойство Тип Описание
savePath? string Необязательный параметр. Путь для сохранения результатов операции.
saveResultsSeparately? boolean Необязательный параметр. Определяет, сохранять ли результаты по каждому файлу в отдельный JSON-файл или в один.

Интерфейс ISignStampAppearance#

Интерфейс ISignStampAppearance описывает параметры для штампа PDF.

Свойство Тип Описание
mockupSettings IMockupSettings Настройки внешнего вида штампа подписи
requisitesSettings IRequisitesSettings Настройки содержимого штампа (реквизиты)
pageSelection string Определяет, на какой странице или страницах будет отображаться штамп. Значения: "all", "last", "some".
pageNumbers? string Необязательный параметр. Страница или диапазон страниц. Пример: "3" или "1-7".

Интерфейс IMockupSettings#

Интерфейс IMockupSettings описывает параметры внешнего вида штампа.

Свойство Тип Описание
position string Положение штампа внутри области: "fitArea", "actualSize", "fitMockup".
addBackground boolean Будет ли добавлен фон на область
addBorders boolean Будет ли добавлена граница на область
logotype? string/boolean Необязательный параметр. Логотип для штампа: Base64 изображения или boolean.

Интерфейс IRequisitesSettings#

Интерфейс IRequisitesSettings описывает содержимое (реквизиты) штампа подписи.

Свойство Тип Описание
position string Расположение реквизитов: "default", "left", "right", "leftAndRight".
centralDisplayType string Внешний вид: "byGost" (по ГОСТ), "arbitrary" (произвольно).
central IPdfCertRequisite[] Реквизиты центральной части
left IPdfCertRequisite[] Реквизиты левой части
right IPdfCertRequisite[] Реквизиты правой части

Интерфейс IPdfCertRequisite#

Свойство Тип Описание
title string Заголовок
dataKey? string Необязательный параметр. Название поля сертификата, значение которого будет использовано.
isEditable boolean Доступно ли редактирование поля. Если false, значение берётся из editedValue или из сертификата по dataKey.
editedValue? string Необязательный параметр. Значение реквизита.
editedValueCharLimit? number Необязательный параметр. Максимальная длина строки.

Интерфейс IPdfAreaDimensions#

Интерфейс IPdfAreaDimensions описывает координаты и размеры области штампа PDF.

Свойство Тип Описание
height number Высота области под штамп (мм)
width number Ширина области под штамп (мм)
horizontalPadding number Отступ от левого края документа (мм)
verticalPadding number Отступ от нижнего края документа (мм)

Интерфейс приложения#

При выполнении операции подписи по ссылке, не относящийся к процедуре интерфейс блокируется.

Пользователю доступны: выбор сертификата, часть настроек подписи (если не заблокированы через apiLockedFields). Параметры, переданные в IExtra, блокируют соответствующие поля в интерфейсе.

Кнопка «Выполнить» заменяется на «Подпись» и «Отмена». После выполнения команды, приложение будет свернуто в системный трей.

При операциях проверки подписи (VERIFYSIGN) окно приложения остаётся видимым после выполнения (не сворачивается в трей).

Для повышения удобства работы и хранения данных веб-сайт TRUSTED.RU использует файлы COOKIE. Продолжая работу с веб-сайтом, Вы даете свое согласие на работу с этими файлами.