Integración de API

sslTrus ofrece una API de firma de código remota, adecuada para desarrolladores que necesiten desarrollar sus propios clientes de firma, sistemas de compilación u otros programas de integración de firma.

La API recibe el resumen del archivo calculado por el cliente; el servicio de firma de código remota completa la firma con la clave privada utilizando el certificado de firma de código especificado y devuelve el resultado de la firma.

El cliente es responsable de:

Calcular el resumen de los datos por firmar.
Construir la estructura de firma requerida por el archivo de destino.
Llamar a la interfaz de firma remota.
Escribir el resultado de firma devuelto en el archivo de destino o en la estructura de firma.
Reportar el resultado final del procesamiento del cliente según sea necesario.

La clave privada de firma de código se mantiene siempre en el HSM en la nube y no se devuelve al cliente a través de la API.

Dirección de acceso

Dirección predeterminada del entorno de producción:

https://ssl.face.racent.com

Entorno NICSRS:

https://ssl.face.nicsrs.com

Interfaz de firma completa:

POST https://ssl.face.racent.com/v1/codesign/sign

Interfaz de informe de resultados:

POST https://ssl.face.racent.com/v1/codesign/report-sign

Si el entorno de entrega real utiliza otras direcciones de servicio, prevalecerán las direcciones proporcionadas por el equipo de entrega u operaciones.

Autenticación de identidad

La API utiliza autenticación básica HTTP.

Correspondencia:

Username = Access Key
Password = Access Secret

Encabezados de la solicitud:

Authorization: Basic <base64(accessKey:accessSecret)>

Por ejemplo:

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

En el uso real de curl, puede proporcionarse directamente mediante el parámetro -u:

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret es una credencial sensible y no debe incluirse en el código fuente, archivos de configuración públicos, registros ni páginas front-end.

Formato de solicitud general

La API utiliza:

HTTPS
POST
JSON

Encabezados de la solicitud:

Content-Type: application/json
Accept: application/json
Authorization: Basic <credentials>

Formato de respuesta común

La API devuelve una estructura JSON unificada:

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

Descripción de los campos:

Campo	Tipo	Descripción
`code`	integer	Código de estado de negocio, `0` indica éxito
`message`	string	Mensaje de estado o de error
`data`	object	Datos de negocio de la interfaz

El cliente debe verificar tanto el código de estado HTTP como el código de estado de negocio.

Se recomienda proceder de la siguiente manera:

HTTP 非 2xx
    ↓
HTTP 请求失败

HTTP 2xx + code != 0
    ↓
业务失败

HTTP 2xx + code == 0
    ↓
读取 data

No juzgues el éxito de una solicitud de firma únicamente por el código HTTP 200.

Interfaz de firma

Interfaz:

POST /v1/codesign/sign

Esta interfaz se utiliza para enviar el resumen pendiente de firma y obtener el resultado de la firma con clave privada remota.

Parámetros de la solicitud

Ejemplo de 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
  }
}

Parámetros principales:

Parámetro	Tipo	Obligatorio	Descripción
`code`	string	Sí	Número del certificado de firma de código
`digest`	string	Sí	Codificación Base64 de los bytes originales del resumen a firmar
`algorithm`	string	Sí	Algoritmo de resumen
`padding`	string	Sí	Modo de relleno RSA, actualmente fijado en `PKCS1`
`extra`	object	No	Contexto del cliente e información de auditoría

Algoritmo de resumen

Actualmente compatible:

SHA1
SHA256
SHA384
SHA512

Por ejemplo, al usar SHA-256:

{
  "algorithm": "SHA256"
}

algorithm debe ser coherente con el algoritmo de resumen realmente utilizado por digest.

Formato de digest

digest debe ser:

Bytes originales del hash → Base64

No es:

文件内容 Base64

tampoco es:

十六进制哈希字符串

Por ejemplo, si un resumen SHA-256 tiene 32 bytes, esos 32 bytes originales deben codificarse en Base64 antes de enviarse a la interfaz.

padding

Actualmente se utiliza de forma fija:

PKCS1

Es decir:

{
  "padding": "PKCS1"
}

No pase otros métodos de relleno.

extra

extra se utiliza para registrar el contexto del cliente, información de auditoría y facilitar la resolución de problemas.

Soporta:

Campo	Tipo	Descripción
`platform`	string	Plataforma del cliente
`version`	string	Versión del cliente
`revision`	string	Revisión de compilación del cliente
`time`	string	Hora de compilación u hora de registro del lado de la solicitud
`hostname`	string	Nombre de host que inicia la solicitud
`signing_filename`	string	Nombre del archivo firmado o ruta local
`signing_filesize`	integer	Tamaño del archivo, en bytes

Por ejemplo:

{
  "extra": {
    "platform": "linux/amd64",
    "version": "1.2.0",
    "hostname": "github-runner-01",
    "signing_filename": "app.exe",
    "signing_filesize": 5242880
  }
}

Si signing_filename contiene directorios internos, nombres de usuario u otra información confidencial, se recomienda enmascararla según la política de seguridad del lado del cliente.

Ejemplo de solicitud de firma

Usando curl:

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": "linux/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 firmada

Respuesta exitosa:

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

Campos de respuesta:

Campo	Tipo	Descripción
`id`	string	ID del registro de firma
`signature`	string	Codificación Base64 del resultado de la firma RSA

Para la capacidad de firma real, el cliente utiliza principalmente:

data.signature

Si necesita informar el estado final después de completar el procesamiento local, también debe guardar:

data.id

Flujo de procesamiento del cliente

Flujo típico:

读取待签名文件
      ↓
按照目标格式生成待签名数据
      ↓
计算摘要
      ↓
Base64 编码摘要
      ↓
POST /v1/codesign/sign
      ↓
获得 signature
      ↓
构造最终签名结构
      ↓
写回目标文件
      ↓
POST /v1/codesign/report-sign

Ten en cuenta lo siguiente:

/v1/codesign/sign

Solo se encarga de la firma remota de la clave privada subyacente.

La estructura de firma de PE Authenticode, JAR, PDF u otros formatos de archivo es gestionada por el cliente según el formato de destino.

Reporte del resultado de la firma

Interfaz:

POST /v1/codesign/report-sign

Después de que el cliente recibe el resultado de la firma remota, aún pueden ocurrir fallos en procesos posteriores, por ejemplo:

Error al construir la estructura de firma final.
Error al escribir en el archivo de destino.
Error de permisos en el archivo local.
Excepción en el procesamiento posterior del cliente.

Puede utilizar esta interfaz para devolver el estado final del procesamiento al servidor.

Parámetros de la solicitud

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

Parámetros:

Campo	Tipo	Obligatorio	Descripción
`id`	string	Sí	El ID del registro de firma devuelto por `/v1/codesign/sign`
`status`	integer	Sí	Estado final del procesamiento en el cliente

Valores de estado:

Estado	Descripción
`1`	Procesamiento final en el cliente exitoso
`2`	Procesamiento final en el cliente fallido

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
}

Veces de firma

Las veces de firma de la API se calculan según si la operación de firma remota se realizó correctamente.

Cuando:

HTTP 2xx
code == 0
data.signature 非空

Cuando se cumplan simultáneamente, se considerará una firma exitosa:

签名次数 +1

Los siguientes casos no consumen el número de firmas:

Fallo de autenticación.
Error de parámetros.
Fallo en la solicitud de red.
Fallo en la solicitud de negocio.
El servidor no devuelve correctamente el contenido de la firma.

Se debe prestar especial atención a:

/v1/codesign/report-sign

Solo informa del estado final del procesamiento del cliente; no constituye una nueva operación de firma ni aumenta o disminuye el número de firmas.

Incluso si el cliente ha obtenido con éxito el resultado de la firma remota, pero posteriormente falla al escribir el archivo localmente, la firma remota con clave privada que se completó exitosamente ya habrá generado un conteo de firma.

Para más reglas de conteo, consulte Material de referencia.

Manejo de errores

El cliente debe manejar por separado:

Errores de red.
Errores HTTP.
Errores de negocio de la API.
Errores de procesamiento local del cliente.

Fallo de autenticación

Por ejemplo:

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

Debe verificar:

Si el Access Key es correcto.
Si el Access Secret es correcto.
Si la solicitud incluye correctamente el encabezado Authorization.

Error de parámetros

Por ejemplo:

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

Se debe prestar especial atención a lo siguiente:

Si code es correcto.
Si digest es un Base64 válido.
Si algorithm coincide con el resumen.
Si padding es PKCS1.

El cliente no debe depender de valores fijos:

message

Las cadenas ejecutan la lógica del programa.

El procesamiento empresarial debe basarse prioritariamente en los códigos de estado y en el contrato de la interfaz.

Tiempo de espera y reintentos

Al llamar a la interfaz de firma remota, se debe establecer un tiempo de espera de red razonable.

Cuando sea necesario reintentar, se debe prestar especial atención a:

签名接口不是普通查询接口

Si el cliente no recibe una respuesta debido a una anomalía de red, no significa necesariamente que el servidor no haya completado la firma.

Por lo tanto, al diseñar un mecanismo de reintento automático, se debe evitar reenviar la solicitud de firma de forma ilimitada o incondicional.

Se recomienda registrar por separado:

Hora de inicio de la solicitud.
Número de certificado de destino.
Identificador del resumen.
Estado HTTP.
Código de estado del negocio.
ID del registro de firma devuelto.
Estado de procesamiento final del cliente.

No registre el Access Secret completo en los logs.

Registros y auditoría

Se recomienda registrar el contexto necesario de la firma, por ejemplo:

certificate code
platform
client version
hostname
filename
filesize
sign record id
result

Para:

digest
signature

Para datos de gran longitud, no se recomienda escribirlos completos en los registros ordinarios.

Se puede registrar:

La longitud.
El hash.
El prefijo y sufijo después de enmascarar.

La ruta del archivo también puede contener nombres de usuario, nombres de proyecto o información de directorios internos, y debe decidirse si se enmascara según los requisitos de seguridad reales.

Notas de seguridad

Al integrar la API, se recomienda seguir estos principios:

Access Secret no debe guardarse en el código frontend.
No se debe enviar Access Secret al repositorio Git.
No registrar el Authorization Header completo en los registros ordinarios.
No registrar el Access Secret completo.
Aplicar el enmascaramiento necesario en los registros para digest y signature.
Llamar al servicio de firma remota a través de HTTPS.
El cliente debe validar el estado HTTP y el estado de negocio.
Establecer tiempos de espera y políticas de reintentos razonables para las solicitudes de red.

La API de firma de código remota devuelve el resultado de la firma, no la clave privada.

La clave privada de firma de código permanece siempre en el HSM remoto.

Cuándo usar la API

Si el método de integración existente ya satisface las necesidades, normalmente se puede usar directamente la herramienta correspondiente.

Escenario	Método recomendado
Firmar directamente archivos EXE, DLL, MSI, etc.	Herramienta de cliente
Software de Windows como Microsoft SignTool, Visual Studio, etc.	Windows Provider
Firma de archivos JAR	Integración Java
Compilación automática con GitHub Actions, Electron Builder, etc.	CI/CD y herramientas de compilación
Desarrollar un cliente de firma propio	API
Implementar por cuenta propia el flujo de firma de formatos de archivo	API
Necesidad de controlar directamente el resumen y el resultado de la firma	API

La API es más adecuada para desarrolladores que necesitan controlar el flujo de firma de bajo nivel.

Si solo necesita completar la firma de código en archivos comunes, dar prioridad a los clientes existentes o a los Providers estándar puede reducir el trabajo de manejar por cuenta propia los formatos de archivo de firma.

Dirección de acceso​

Autenticación de identidad​

Formato de solicitud general​

Formato de respuesta común​

Interfaz de firma​

Parámetros de la solicitud​

Algoritmo de resumen​

Formato de digest​

padding​

extra​

Ejemplo de solicitud de firma​

Respuesta firmada​

Flujo de procesamiento del cliente​

Reporte del resultado de la firma​

Parámetros de la solicitud​

Ejemplo de solicitud​

Respuesta exitosa​

Veces de firma​

Manejo de errores​

Fallo de autenticación​

Error de parámetros​

Tiempo de espera y reintentos​

Registros y auditoría​

Notas de seguridad​

Cuándo usar la API​

Dirección de acceso

Autenticación de identidad

Formato de solicitud general

Formato de respuesta común

Interfaz de firma

Parámetros de la solicitud

Algoritmo de resumen

Formato de digest

padding

extra

Ejemplo de solicitud de firma

Respuesta firmada

Flujo de procesamiento del cliente

Reporte del resultado de la firma

Parámetros de la solicitud

Ejemplo de solicitud

Respuesta exitosa

Veces de firma

Manejo de errores

Fallo de autenticación

Error de parámetros

Tiempo de espera y reintentos

Registros y auditoría

Notas de seguridad

Cuándo usar la API