Saltar al contenido principal

Referencia de la API de firma de código remota

Este artículo está dirigido a desarrolladores que necesitan integrar directamente capacidades de firma remota, y describe las siguientes dos interfaces:

  • POST /v1/codesign/sign: Envía el resumen hash pendiente de firma y obtiene el resultado de firma RSA PKCS#1.
  • POST /v1/codesign/report-sign: Reporta el resultado final del procesamiento del cliente (no afecta el conteo de firmas).

Dirección de acceso​

EntornoDirección
Entorno de producción (predeterminado)https://ssl.face.racent.com
Entorno NICSRShttps://ssl.face.nicsrs.com

Para direcciones de otros entornos, prevalezca la dirección proporcionada por entrega u operaciones.

Convenciones generales​

Formato de solicitud​

  • Protocolo: HTTPS
  • Método: POST
  • Cuerpo: JSON
  • Encabezados:
Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

Autenticación​

La interfaz utiliza HTTP Basic Auth:

  • Username: Access Key
  • Password: Access Secret

Generar el encabezado Authorization:

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

Estructura de respuesta general​

{
  "code": 0,
  "message": "ok",
  "data": {}
}
CampoTipoSignificado
codeintegerCódigo de estado del negocio. 0 indica éxito, un valor distinto de 0 indica fallo del negocio.
messagestringDescripción del estado del negocio; en caso de fallo, es la descripción del error.
dataobjectDatos comerciales de la interfaz.

El llamador debe procesar tanto el código de estado HTTP como el código de estado del negocio:

  • HTTP no 2xx → Tratar como error HTTP.
  • HTTP 2xx y code != 0 → Tratar como error de negocio.
  • HTTP 2xx y code == 0 → Leer el data correspondiente.

Interfaz de firma​

Descripción de la interfaz​

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
  }
}
CampoTipoObligatorioDescripción
codestringSíNúmero de certificado, utilizado para seleccionar el certificado de firma remota.
digeststringSíCodificación Base64 de los bytes brutos del hash a firmar. El llamador debe calcular el hash localmente de acuerdo con el archivo de destino y los requisitos de la herramienta de firma.
algorithmstringSíAlgoritmo de hash, admite SHA1, SHA256, SHA384, SHA512.
paddingstringSíModo de relleno RSA, actualmente fijo en PKCS1.
extraobjectNoInformación de contexto del cliente, utilizada para registros de firma, auditoría y resolución de problemas.

Descripción del campo extra:

CampoTipoSignificado
platformstringPlataforma del cliente, como windows/amd64, linux/amd64.
versionstringVersión del cliente.
revisionstringRevisión de la compilación del cliente.
timestringHora de compilación del cliente u hora de la solicitud.
hostnamestringNombre del host que inicia la firma.
signing_filenamestringNombre o ruta del archivo firmado; se recomienda enmascarar según la política de seguridad.
signing_filesizeintegerTamaño del archivo firmado (bytes).

Ejemplo de solicitud​

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

Después de que el cliente obtenga el resultado de la firma remota, puede fallar al procesarlo localmente, escribirlo o devolverlo al llamante. Esta interfaz se utiliza para devolver el estado de procesamiento final del cliente al servidor, lo que facilita la visualización de los registros de firma y la auditoría.

Nota

Esta interfaz solo registra el resultado del procesamiento del cliente, no cambia el resultado de conteo de /v1/codesign/sign. No llamar a esta interfaz no afecta el número de firmas exitosas.

Parámetros de solicitud​

{
  "id": "735985894427246592",
  "status": 1
}
CampoTipoObligatorioDescripción
idstringSí/v1/codesign/sign devuelto por data.id.
statusintegerSíEstado final del procesamiento del cliente: 1 significa éxito, 2 significa fallo.

Ejemplo de solicitud​

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

Respuesta exitosa​

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

Ejemplo de respuesta de error​

Fallo de autenticación:

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

Parámetro incorrecto:

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

具体错误码和错误信息以服务端实际返回为准。接入方不应依赖固定错误文案做业务分支判断。

接入建议​

  • 妥善保护 Access Secret，不要写入日志、崩溃报告或前端页面。
  • digest 必须是哈希原始字节的 Base64 编码，不是十六进制字符串，也不是完整文件内容。
  • algorithm 必须与 digest 的实际哈希算法一致。
  • 当前填充模式固定使用 PKCS1，不要传入其他值。
  • digest 和 signature 字段可能较长，日志中建议只记录长度或前后缀脱敏结果。
  • 建议在客户端完成最终处理后调用 report-sign 上报结果，便于后续审计排查。
  • 对网络错误、HTTP 错误和业务错误分别处理，并为签名请求设置合理的超时和重试策略。
Última actualización en