Команда signAndEncrypt — описание и примеры#
Команда signAndEncrypt API КриптоАРМ предназначена для подписи, шифрования и проверки документов при интеграции с внешними системами. Она позволяет безопасно обрабатывать одиночные файлы и пакеты документов через JSON-RPC, поддерживает различные режимы операций и может использоваться как механизм аутентификации.
Содержание:
- Общая информация
- Формат ссылки
- Описание запросов и ответов
- Получение параметров операции
- Отправка результатов операций
- Справочник интерфейсов
- Интерфейс приложения
Общая информация#
Команда signAndEncrypt (подпись и шифрование) используется для запроса на подпись документа или пакета документов. Может использоваться в качестве аутентификатора.
📌 Выполнение операции требует действующей лицензии на КриптоАРМ.

Формат ссылки#
Для выполнения команды signAndEncrypt должна быть сформирована ссылка вида:
cryptoarm://- зарегистрированный протоколsignAndEncrypt- выполняемая команда<URL>- ссылка на получение JSON с параметрами, нужными для выполнения команды?id=<id>- обязательный параметр. Идентификатор транзакции.&authType=<authType>- необязательный параметр. Тип аутентификации.
Пример:
Описание запросов и ответов#
Все запросы между КриптоАРМ и сервером ДОЛЖНЫ соответствовать спецификации протокола 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. |
Пример:
Формат ответа#
| Ключ | Значение | Описание |
|---|---|---|
| jsonrpc | «2.0» | Версия JSON-RPC протокола. Всегда «2.0». |
| result | ISignAndEncryptParameters | Объект со сведениями о параметрах операции подписи |
| id | Уникальный идентификатор | Используется идентификатор, который указан в ссылке на операцию. |
Пример для прямых операций (SIGN + ARCHIVE + ENCRYPT):
Пример для проверки подписи (VERIFYSIGN):
Отправка результатов операций#
Отправка результата прямых операций#
После того, как пользователь выберет нужные сертификаты, КриптоАРМ выполняет операцию. Результаты отправляются 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 | Сведения о результатах прямой операции |
Вариант 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 | Сведения о проверке подписи |
Для операций
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) окно приложения остаётся видимым после выполнения (не сворачивается в трей).