Перейти к основному содержимому

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

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

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

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

СредаАдрес
Производственная среда (по умолчанию)https://ssl.face.racent.com
Среда NICSRShttps://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": {}
}
ПолеТипЗначение
codeintegerКод состояния бизнес-операции. 0 означает успех, значение, отличное от 0, означает ошибку бизнес-операции.
messagestringОписание состояния бизнес-операции; при ошибке содержит описание ошибки.
dataobjectБизнес-данные интерфейса.

Вызывающая сторона должна одновременно обрабатывать 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
  }
}
ПолеТипОбязательноеОписание
codestringДаНомер сертификата, используется для выбора сертификата удалённой подписи.
digeststringДаBase64-кодировка исходных байтов хеша, ожидающего подпись. Вызывающая сторона должна вычислить хеш локально в соответствии с целевым файлом и требованиями средства подписи.
algorithmstringДаАлгоритм хеширования, поддерживаются SHA1, SHA256, SHA384, SHA512.
paddingstringДаРежим заполнения RSA, в настоящее время фиксирован как PKCS1.
extraobjectНетКонтекстная информация клиента, используемая для записи подписи, аудита и устранения неполадок.

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

ПолеТипОписание
platformstringПлатформа клиента, например windows/amd64, linux/amd64.
versionstringВерсия клиента.
revisionstringРевизия сборки клиента.
timestringВремя сборки клиента или время запроса.
hostnamestringИмя хоста, инициировавшего подпись.
signing_filenamestringИмя или путь подписываемого файла; рекомендуется маскировать в соответствии с политикой безопасности.
signing_filesizeintegerРазмер подписываемого файла (в байтах).

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

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"
  }
}
ПолеТипОписание
idstringИдентификатор записи подписи, используется при вызове report-sign.
signaturestringРезультат RSA-подписи в кодировке Base64.

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

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

POST /v1/codesign/report-sign

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

Примечание

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

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

{
  "id": "735985894427246592",
  "status": 1
}
ПолеТипОбязательноеЗначение
idstringДаdata.id, возвращённый /v1/codesign/sign.
statusintegerДаИтоговый статус обработки на стороне клиента: 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 и бизнес-ошибки раздельно и настраивайте разумные таймауты и политику повторов для подписанных запросов.
Последнее обновление