跳到主要内容
版本：V1.3.8

远程代码签名 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": {}
}
字段类型含义
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客户端构建 revision。
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签名记录 ID，调用 report-sign 时使用。
signaturestringRSA 签名结果的 Base64 编码。

上报签名结果​

接口说明​

POST /v1/codesign/report-sign

客户端在获取远程签名结果后，可能在本地处理、写入或交还调用方时失败。该接口用于把客户端最终处理状态回传给服务端，便于签名记录展示和审计排查。

说明

该接口只记录客户端处理结果，不改变 /v1/codesign/sign 的计次结果。不调用此接口不影响签名成功次数。

请求参数​

{
  "id": "735985894427246592",
  "status": 1
}
字段类型必填含义
idstring是/v1/codesign/sign 返回的 data.id。
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 错误和业务错误分别处理，并为签名请求设置合理的超时和重试策略。
最后于 更新