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

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

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

Содержание:

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

Команда certrequests используется для генерации запроса на сертификат по шаблону.

Схема взаимодействия:

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

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

В качестве транспорта используется HTTP.

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

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

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

cryptoarm://certrequests/<URL>/?id=<id>[&authType=<authType>]
  • cryptoarm:// - зарегистрированный протокол
  • certrequests - выполняемая команда
  • <URL> - ссылка, на которую КриптоАРМ будет слать запросы
  • id - уникальный идентификатор транзакции
  • authType - необязательный параметр. Тип аутентификации.

Пример:

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

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

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

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

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

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "certrequests.parameters",
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
    "diagnostic": {
    }
}

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

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

Пример ответа с шаблоном JSONTemplate:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
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": "GENERATE",
        "props": {
            "templateType": "JSONTemplate",
            "template": {
                "Description": "",
                "FriendlyName": "Пользователь",
                "RDN": [{
                    "Oid": "2.5.4.3",
                    "Name": "CN",
                    "Length": 64,
                    "LocalizedName": "Общее имя",
                    "SettingsValues": [],
                    "DefaultValue": null,
                    "ProhibitAnyValue": false,
                    "ProhibitChange": false,
                    "ProhibitEmpty": true
                }],
                "Extensions": {
                    "KeyUsage": [{
                        "Name": "cRLSign",
                        "LocalizedName": "Автономное подписание списка отзыва (CRL)",
                        "DefaultValue": false,
                        "ProhibitChange": true
                    }],
                    "ExtendedKeyUsage": [{
                        "Name": "1.3.6.1.5.5.7.3.1",
                        "LocalizedName": "Проверка подлинности сервера",
                        "DefaultValue": false,
                        "ProhibitChange": true
                    }]
                },
                "MarkExportable": false
            }
        }
    },
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

Пример ответа с шаблоном CertificateTemplate (на основе сертификата):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
HTTP/1.1 200 OK
Content-Type: application/json
{
    "jsonrpc": "2.0",
    "result": {
        "operation": "GENERATE",
        "props": {
            "templateType": "CertificateTemplate",
            "template": {
                "certificateBase64": "MIIFFDCCBMGgAwIBAgIQT...4VVkDWbX/n4="
            }
        }
    },
    "id": "2c48eb32-a0a8-405c-ade9-eed130605cba"
}

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

После генерации запроса, он будет отправлен на сервер.

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

Ключ Значение Описание
jsonrpc «2.0» Версия JSON-RPC протокола. Всегда «2.0».
method certrequests.base64 Используемый метод.
params ICertificaterequestBase64Params Параметры, содержащие запрос

Пример:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
Content-Type: application/json
Content-Length: ...
Accept: application/json
{
    "jsonrpc": "2.0",
    "method": "certrequests.base64",
    "params": {
        "id": "2c48eb32-a0a8-405c-ade9-eed130605cba",
        "certificaterequestBase64": "MIIFFDCCBMGgAwIBAgIQTm1HiybyfWV...4VVkDWbX/n4=",
        "friendlyName": "ООО Рога и Копыта"
    }
}

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

Интерфейс ICertrequestsParameters#

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

Свойство Тип Описание
operation string Тип операции. Единственное поддерживаемое значение: GENERATE.
props ICertrequestsOperationGenerateProps Параметры операции

Интерфейс ICertrequestsOperationGenerateProps#

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

Свойство Тип Описание
headerText? string Необязательный параметр. Используется для отображения в заголовке окна. Максимальная длина: 40 символов.
descriptionText? string Необязательный параметр. Используется для отображения в сведениях об операции. Максимальная длина: 120 символов.
templateType string Тип шаблона: "JSONTemplate" (JSON-описание) или "CertificateTemplate" (на основе существующего сертификата).
template IJSONTemplate или ICertificateTemplate Шаблон для генерации запроса на сертификат.

Интерфейс IJSONTemplate#

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

Свойство Тип Описание
Description string Описание шаблона
FriendlyName string Дружественное имя шаблона
RDN IRDN[] Набор полей DN (Distinguished Name)
Extensions IRequestExtension Расширения сертификата
MarkExportable boolean Определяет экспортируемость ключей

Интерфейс IRDN#

Свойство Тип Описание
Oid string OID поля
Name string Наименование OID
Length number Максимальная длина поля
LocalizedName string Локализованное наименование OID
SettingsValues string[] Список возможных значений
DefaultValue string Значение по умолчанию
ProhibitAnyValue boolean Флаг, указывающий, что пользователю доступны только значения из SettingsValues
ProhibitChange boolean Флаг, указывающий, что поле не может быть изменено
ProhibitEmpty boolean Флаг, указывающий, что поле должно быть непустым

Интерфейс IRequestExtension#

Свойство Тип Описание
KeyUsage IKeyUsage[] Использование ключа
ExtendedKeyUsage IExtendedKeyUsage[] Расширенное использование ключа

Интерфейс IKeyUsage#

Свойство Тип Описание
Name string Наименование OID (например, "digitalSignature")
LocalizedName string Локализованное наименование OID
DefaultValue boolean Значение по умолчанию
ProhibitChange boolean Флаг, указывающий, что поле не может быть изменено

Интерфейс IExtendedKeyUsage#

Свойство Тип Описание
Name string Наименование OID (например, "1.3.6.1.5.5.7.3.1")
LocalizedName string Локализованное наименование OID
DefaultValue boolean Значение по умолчанию
ProhibitChange boolean Флаг, указывающий, что поле не может быть изменено

Интерфейс ICertificateTemplate#

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

Свойство Тип Описание
certificateBase64 string Сертификат в формате X.509, закодированный в Base64

Интерфейс ICertificaterequestBase64Params#

Свойство Тип Описание
id string Идентификатор транзакции
certificaterequestBase64 string Запрос в формате X.509, закодированный в Base64
friendlyName string Дружественное имя субъекта

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

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

Пользователю доступны:

  • Заполнение полей запроса,
  • Кнопки «Готово» и «Отмена».

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

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