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

Entorno	Dirección
Entorno de producción (predeterminado)	https://ssl.face.racent.com
Entorno NICSRS	https://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": {}
}

Campo	Tipo	Significado
code	integer	Código de estado del negocio. 0 indica éxito, un valor distinto de 0 indica fallo del negocio.
message	string	Descripción del estado del negocio; en caso de fallo, es la descripción del error.
data	object	Datos 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

Envía los bytes originales del hash que se va a firmar (codificados en Base64). El servicio remoto utiliza el certificado especificado para generar una firma RSA PKCS#1 y devuelve el resultado.

Atención

Cuando /v1/codesign/sign devuelve correctamente el contenido de la firma, se considera que la firma ha finalizado con éxito y el contador de firmas aumenta en 1. Las solicitudes fallidas no consumen firmas. La llamada a report-sign no afecta al recuento.

Parámetros de la solicitud

{
  "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
  }
}

Campo	Tipo	Obligatorio	Descripción
code	string	Sí	Número de certificado, utilizado para seleccionar el certificado de firma remota.
digest	string	Sí	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.
algorithm	string	Sí	Algoritmo de hash, admite SHA1, SHA256, SHA384, SHA512.
padding	string	Sí	Modo de relleno RSA, actualmente fijo en PKCS1.
extra	object	No	Información de contexto del cliente, utilizada para registros de firma, auditoría y resolución de problemas.

Descripción del campo extra:

Campo	Tipo	Significado
platform	string	Plataforma del cliente, como windows/amd64, linux/amd64.
version	string	Versión del cliente.
revision	string	Revisión de la compilación del cliente.
time	string	Hora de compilación del cliente u hora de la solicitud.
hostname	string	Nombre del host que inicia la firma.
signing_filename	string	Nombre o ruta del archivo firmado; se recomienda enmascarar según la política de seguridad.
signing_filesize	integer	Tamañ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

Respuesta correcta

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

Campo	Tipo	Significado
id	string	ID del registro de firma, utilizado al llamar a report-sign.
signature	string	Resultado de la firma RSA codificado en Base64.

---

Informar del resultado de la firma

Descripción de la API

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
}

Campo	Tipo	Obligatorio	Descripción
id	string	Sí	/v1/codesign/sign devuelto por data.id.
status	integer	Sí	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
}

Atención

Los códigos y mensajes de error concretos dependen de la respuesta real del servidor. La aplicación cliente no debe basar sus decisiones de negocio en textos de error fijos.

---

Recomendaciones de integración

• Proteja adecuadamente Access Secret y no lo incluya en registros, informes de fallos ni páginas del cliente web.
• digest debe ser la codificación Base64 de los bytes originales del hash, no una cadena hexadecimal ni el contenido completo del archivo.
• algorithm debe coincidir con el algoritmo de hash real de digest.
• El modo de relleno actual es PKCS1; no envíe otros valores.
• Los campos digest y signature pueden ser largos. Se recomienda registrar únicamente su longitud o un prefijo y un sufijo enmascarados.
• Se recomienda llamar a report-sign una vez finalizado el procesamiento en el cliente para informar del resultado y facilitar las auditorías y el diagnóstico posteriores.
• Gestione por separado los errores de red, HTTP y de negocio, y configure tiempos de espera y estrategias de reintento adecuados para las solicitudes de firma.