Referencia de la API de firma de código remota

Este documento está dirigido a desarrolladores que necesitan integrar directamente la capacidad de firma remota y describe las siguientes dos interfaces:

• POST /v1/codesign/sign: envía el resumen hash que se va a firmar y obtiene el resultado de la firma RSA PKCS#1.
• POST /v1/codesign/report-sign: informa el resultado final del procesamiento del cliente (no afecta el recuento 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

Si necesita direcciones de otros entornos, prevalecerá la dirección proporcionada por el equipo de 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 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 de negocio de la interfaz.

El llamador debe manejar simultáneamente el código de estado HTTP y el código de estado del negocio:

• HTTP distinto de 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íe los bytes sin procesar del hash pendiente de firma (codificados en Base64). El servicio remoto completa la firma RSA PKCS#1 utilizando el certificado especificado y devuelve el resultado.

Nota

/v1/codesign/sign Si se devuelve correctamente el contenido de la firma, se considera que la firma fue exitosa y el contador de firmas se incrementa en 1. Las solicitudes fallidas no consumen el recuento de firmas. Llamar o no a report-sign no afecta el conteo.

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	Significado
code	string	Sí	Número de certificado, utilizado para seleccionar el certificado de firma remota.
digest	string	Sí	Codificación Base64 de los bytes originales del hash que se va a firmar. La parte que realiza la llamada debe calcular el hash localmente según 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 fijado en PKCS1.
extra	object	no	Información de contexto del cliente, utilizada para el registro de firmas, auditorías y resolución de problemas.

Descripción de los campos de 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 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 desensibilizar según la política de seguridad.
signing_filesize	integer	Tamaño del archivo firmado (en 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 exitosa

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

Campo	Tipo	Significado
id	string	ID del registro de firma, se utiliza al llamar a report-sign.
signature	string	Codificación Base64 del resultado de la firma RSA.

---

Reportar el resultado de la firma

Descripción de la interfaz

POST /v1/codesign/report-sign

Después de obtener el resultado de la firma remota, el cliente puede fallar al procesarlo localmente, escribirlo o devolverlo al llamador. Esta interfaz se utiliza para devolver el estado de procesamiento final del cliente al servidor, facilitando la visualización del registro de firma y la investigación de auditoría.

Nota

Esta interfaz solo registra el resultado del procesamiento del cliente y no cambia el resultado del conteo de /v1/codesign/sign. No llamar a esta interfaz no afecta la cantidad de firmas exitosas.

Parámetros de la solicitud

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

Campo	Tipo	Obligatorio	Significado
id	string	Sí	El data.id devuelto por /v1/codesign/sign.
status	integer	Sí	Estado de procesamiento final 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
}

Error de parámetro:

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

Nota

Los códigos de error y mensajes de error específicos están sujetos a lo que el servidor devuelva realmente. La parte integradora no debe depender de textos de error fijos para realizar bifurcaciones de lógica de negocio.

---

Recomendaciones de integración

• Proteja adecuadamente el Access Secret y no lo escriba en registros, informes de fallos ni páginas de front-end.
• 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 se fija en PKCS1; no pase otros valores.
• Los campos digest y signature pueden ser largos; se recomienda registrar solo la longitud o el resultado enmascarado de prefijo y sufijo en los registros.
• Se recomienda llamar a report-sign para informar el resultado después de que el cliente complete el procesamiento final, a fin de facilitar la auditoría y la resolución de problemas posteriores.
• Trate por separado los errores de red, los errores HTTP y los errores de negocio, y establezca tiempos de espera razonables y una estrategia de reintentos para las solicitudes firmadas.