Справочник по API удалённого подписания кода

Этот документ предназначен для разработчиков, которым требуется напрямую интегрировать возможности удалённого подписания. В нём описаны следующие два интерфейса:

• POST /v1/codesign/sign: передача хеш-дампа, ожидающего подписания, и получение результата подписи RSA PKCS#1.
• POST /v1/codesign/report-sign: передача итогового результата обработки на стороне клиента (не влияет на учёт количества подписаний).

---

Адрес подключения

Среда	Адрес
Производственная среда (по умолчанию)	https://ssl.face.racent.com
Среда NICSRS	https://ssl.face.nicsrs.com

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

---

Общие соглашения

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

• Протокол: HTTPS
• Method: POST
• Body: JSON
• Headers:

Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

Аутентификация

Интерфейс использует HTTP Basic Auth:

• Username: Access Key
• Password: Access Secret

Сгенерируйте заголовок Authorization:

printf "%s:%s" "$ACCESS_KEY" "$ACCESS_SECRET" | base64

Общая структура ответа

{
  "code": 0,
  "message": "ok",
  "data": {}
}

Поле	Тип	Значение
code	integer	Код состояния бизнес-операции. 0 означает успех, не 0 означает ошибку бизнес-операции.
message	string	Описание состояния бизнес-операции, при ошибке — описание ошибки.
data	object	Бизнес-данные интерфейса.

Вызывающая сторона должна одновременно обрабатывать HTTP-код состояния и код состояния бизнес-операции:

• HTTP не 2xx → обрабатывать как ошибку HTTP.
• HTTP 2xx и code != 0 → обрабатывать как бизнес-ошибку.
• HTTP 2xx и code == 0 → читать соответствующий data.

---

Интерфейс подписи

Описание интерфейса

POST /v1/codesign/sign

Отправьте исходные байты хеша для подписи (в кодировке Base64). Удалённый сервис выполнит подпись RSA PKCS#1 с использованием указанного сертификата и вернёт результат.

Внимание

/v1/codesign/sign Успешный возврат подписанного содержимого считается успешной подписью, счётчик подписей увеличивается на 1. Неудачные запросы не расходуют количество подписей. Вызов report-sign не влияет на учёт.

Параметры запроса

{
  "code": "CERT_CODE",
  "digest": "BASE64_ENCODED_HASH",
  "algorithm": "SHA256",
  "padding": "PKCS1",
  "extra": {
    "platform": "windows/amd64",
    "version": "1.0.0",
    "revision": "abcdef0",
    "time": "2026-06-12T10:00:00+08:00",
    "hostname": "build-host-01",
    "signing_filename": "Example.exe",
    "signing_filesize": 1048576
  }
}

Поле	Тип	Обязательное	Описание
code	string	Да	Номер сертификата, используется для выбора сертификата удалённой подписи.
digest	string	Да	Base64-кодирование исходных байтов хеша, который нужно подписать. Вызывающая сторона должна вычислить хеш локально в соответствии с целевым файлом и требованиями средства подписи.
algorithm	string	Да	Алгоритм хеширования, поддерживаются SHA1, SHA256, SHA384, SHA512.
padding	string	да	Режим заполнения RSA, в настоящее время фиксирован как PKCS1.
extra	object	нет	Контекстная информация клиента, используемая для записи подписи, аудита и устранения неполадок.

Описание полей extra:

Поле	Тип	Описание
platform	string	Платформа клиента, например windows/amd64, linux/amd64.
version	string	Версия клиента.
revision	string	Ревизия сборки клиента.
time	string	Время сборки клиента или время запроса.
hostname	string	Имя хоста, инициировавшего подпись.
signing_filename	string	Имя или путь подписываемого файла; рекомендуется маскировать согласно политике безопасности.
signing_filesize	integer	Размер подписываемого файла (в байтах).

Пример запроса

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "code": "CERT_CODE",
    "digest": "BASE64_ENCODED_HASH",
    "algorithm": "SHA256",
    "padding": "PKCS1",
    "extra": {
      "platform": "windows/amd64",
      "version": "1.0.0",
      "hostname": "build-host-01",
      "signing_filename": "Example.exe",
      "signing_filesize": 1048576
    }
  }' \
  https://ssl.face.racent.com/v1/codesign/sign

Ответ об успешном выполнении

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "735985894427246592",
    "signature": "BASE64_ENCODED_SIGNATURE"
  }
}

Поле	Тип	Описание
id	string	Идентификатор записи подписи, используется при вызове report-sign.
signature	string	Результат RSA-подписи в кодировке Base64.

---

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

Описание интерфейса

POST /v1/codesign/report-sign

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

Примечание

Этот интерфейс только фиксирует результат обработки на стороне клиента и не изменяет результат подсчёта /v1/codesign/sign. Отсутствие вызова этого интерфейса не влияет на количество успешных подписаний.

Параметры запроса

{
  "id": "735985894427246592",
  "status": 1
}

Поле	Тип	Обязательное	Значение
id	string	Да	data.id, возвращённый /v1/codesign/sign.
status	integer	Да	Итоговый статус обработки на стороне клиента: 1 — успешно, 2 — ошибка.

Пример запроса

curl -u "$ACCESS_KEY:$ACCESS_SECRET" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "735985894427246592",
    "status": 1
  }' \
  https://ssl.face.racent.com/v1/codesign/report-sign

Успешный ответ

{
  "code": 0,
  "message": "ok",
  "data": null
}

---

Пример ответа об ошибке

Ошибка аутентификации:

{
  "code": 401,
  "message": "unauthorized",
  "data": null
}

Ошибка параметров:

{
  "code": 400,
  "message": "invalid request",
  "data": null
}

Примечание

Конкретные коды и сообщения об ошибках зависят от фактического ответа сервера. Интегрирующая сторона не должна полагаться на фиксированные тексты ошибок для ветвления бизнес-логики.

---

Рекомендации по интеграции

• Надлежащим образом защищайте Access Secret: не записывайте его в журналы, отчёты о сбоях или страницы前端.
• digest должен быть Base64-кодировкой исходных байтов хеша, а не шестнадцатеричной строкой и не полным содержимым файла.
• algorithm должен соответствовать фактическому алгоритму хеширования digest.
• В настоящее время режим заполнения фиксированно использует PKCS1, не передавайте другие значения.
• Поля digest и signature могут быть длинными, поэтому в журналах рекомендуется фиксировать только длину или маскированный результат по первым и последним символам.
• Рекомендуется после завершения обработки на стороне клиента вызывать report-sign для отправки результата, что облегчит последующий аудит и диагностику.
• Обрабатывайте сетевые ошибки, HTTP-ошибки и бизнес-ошибки по отдельности, а также задавайте разумные тайм-ауты и стратегию повторных попыток для подписанных запросов.