Integración de API

sslTrus ofrece una API de firma de código remota, diseñada para desarrolladores que necesitan desarrollar sus propios clientes de firma, sistemas de compilación u otras integraciones de firma.

La API recibe el resumen del archivo calculado por el cliente, y el servicio de firma de código remoto utiliza el certificado de firma de código especificado para completar la firma con la clave privada, devolviendo el resultado de la firma.

El cliente es responsable de:

Calcular el resumen de los datos a firmar.
Construir la estructura de firma necesaria para el archivo de destino.
Llamar a la interfaz de firma remota.
Escribir el resultado de la 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 siempre se almacena en el HSM en la nube y nunca 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

NICSRS entorno:

https://ssl.face.nicsrs.com

Interfaz de firma completa:

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

Resultado de la interfaz de reporte de datos:

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

Si el entorno de entrega real utiliza otras direcciones de servicio, prevalezca la dirección proporcionada por el equipo de entrega u operaciones.

Autenticación de identidad

La API utiliza HTTP Basic Auth.

Correspondencia:

Username = Access Key
Password = Access Secret

Cabeceras de la solicitud:

Authorization: Basic <base64(accessKey:accessSecret)>

Por ejemplo:

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

Al usar curl en la práctica, se puede proporcionar directamente mediante el parámetro -u.

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret es una credencial confidencial y no debe incluirse en el código fuente, archivos de configuración públicos, registros ni páginas del cliente web.

Formato general de las solicitudes

La API utiliza:

HTTPS
POST
JSON

Cabeceras de la solicitud:

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

Formato de respuesta general

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 la operación; `0` indica éxito
`message`	string	Información de estado o de error
`data`	object	Datos de la operación de la API

El cliente debe comprobar tanto el código de estado HTTP como el código de estado de la operación.

Se recomienda procesar la respuesta de la siguiente manera:

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

No traduzcas solo con base en HTTP 200 para determinar que una solicitud de firma fue exitosa.

Interfaz de firma

Interfaz:

POST /v1/codesign/sign

Esta interfaz permite enviar el resumen que se va a firmar y obtener el resultado de la firma realizada con la 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í	Código 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í	Método de relleno RSA, actualmente fijado en `PKCS1`
`extra`	object	No	Contexto del cliente e información de auditoría

Algoritmo de resumen

Actualmente se admiten:

SHA1
SHA256

Por ejemplo, al usar SHA-256:

{
  "algorithm": "SHA256"
}

algorithm debe ser consistente con el algoritmo de resumen que digest utiliza realmente.

Formato de digest

digest debe ser:

Bytes originales del hash → Base64

No es:

文件内容 Base64

Tampoco es:

No es tampoco:

十六进制哈希字符串

Por ejemplo, si un resumen SHA-256 tiene 32 bytes en sí mismo, entonces se deben codificar esos 32 bytes originales en Base64 antes de pasarlos a la interfaz.

padding

Actualmente se usa fijamente:

PKCS1

Es decir:

{
  "padding": "PKCS1"
}

No pases otros métodos de relleno.

extra

extra se utiliza para registrar el contexto del cliente, la información de auditoría y ayudar en 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 en el lado de la solicitud
`hostname`	string	Nombre de host que realiza 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 anonimizar o enmascarar esos datos según la política de seguridad del cliente.

Ejemplo de solicitud de firma

Con 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 de firma

Respuesta correcta:

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

Campos devueltos:

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

Tenga en cuenta lo siguiente:

/v1/codesign/sign

Solo es responsable de la firma de la clave privada remota subyacente.

La forma en que PE Authenticode, JAR, PDF u otros formatos de archivo organizan la estructura de firma, es manejada por el cliente según el formato objetivo.

Reportar el resultado de la firma

Interfaz:

POST /v1/codesign/report-sign

El cliente, tras recibir el resultado de la firma remota, aún puede experimentar fallos en el proceso posterior, por ejemplo:

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

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

Parámetros de solicitud

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

Parámetros:

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

Valores de estado:

Estado	Descripción
`1`	El procesamiento final del cliente se completó correctamente
`2`	El procesamiento final del cliente falló

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 correcta

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

Número de firmas

El número de firmas de la API se determina según si la operación de firma remota es exitosa.

Cuando:

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

Cuando se cumplen todas estas condiciones, se considera que se ha completado una firma correctamente:

签名次数 +1

Los siguientes casos no consumen firmas:

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

Debe prestar especial atención a:

/v1/codesign/report-sign

Solo se informa el estado final del procesamiento del cliente, no es una nueva operación de firma y no aumenta ni disminuye el número de firmas.

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

Para más reglas de conteo, consulte Materiales 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
}

Compruebe lo siguiente:

Que Access Key sea correcto.
Que Access Secret sea correcto.
Que la solicitud incluya correctamente la cabecera Authorization.

Error de parámetros

Por ejemplo:

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

Debe prestarse especial atención a:

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

El cliente no debe depender de un:

message

Lógica de ejecución de cadenas de caracteres.

El manejo de negocios debe basarse preferentemente en el código de estado y el contrato de la interfaz.

Tiempo de espera y reintentos

Al invocar la interfaz de firma remota, debe establecerse 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 un error 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 solicitudes de firma de forma ilimitada o incondicional.

Se recomienda registrar por separado:

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

No registrar el Access Secret completo en los registros.

Registros y auditoría

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

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

Para:

digest
signature

Los datos de este tipo, al ser de gran tamaño, no se recomienda escribirlos completos en los registros ordinarios.

Se puede registrar:

La longitud.
El hash.
El prefijo y sufijo después de la desensibilización.

Las rutas de archivo también pueden contener nombres de usuario, nombres de proyecto o información de directorios internos; se debe decidir si desensibilizarlos según los requisitos de seguridad reales.

Notas de seguridad

Al integrar la API, se recomienda seguir los siguientes principios:

Access Secret no debe guardarse en el código del frontend.
Access Secret no debe enviarse al repositorio de Git.
No registrar el encabezado Authorization completo en los registros ordinarios.
No registrar el Access Secret completo.
Aplicar la desensibilización necesaria en los registros para digest y signature.
Llamar al servicio de firma remota mediante HTTPS.
El cliente debe verificar el estado HTTP y el estado empresarial.
Establecer tiempos de espera y estrategias de reintento 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 siempre se conserva 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 de Java
Compilación automática como GitHub Actions, Electron Builder, etc.	CI/CD y herramientas de compilación
Desarrollo propio de un cliente de firma	API
Implementación propia del proceso 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 subyacente.

Si solo se necesita completar la firma de código para archivos comunes, priorizar el uso de clientes existentes o Providers estándar puede reducir el trabajo de procesar manualmente los formatos de archivo de firma.

Dirección de acceso​

Autenticación de identidad​

Formato general de las solicitudes​

Formato de respuesta general​

Interfaz de firma​

Parámetros de la solicitud​

Algoritmo de resumen​

Formato de digest​

padding​

extra​

Ejemplo de solicitud de firma​

Respuesta de firma​

Flujo de procesamiento del cliente​

Reportar el resultado de la firma​

Parámetros de solicitud​

Ejemplo de solicitud​

Respuesta correcta​

Número de firmas​

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 general de las solicitudes

Formato de respuesta general

Interfaz de firma

Parámetros de la solicitud

Algoritmo de resumen

Formato de digest

padding

extra

Ejemplo de solicitud de firma

Respuesta de firma

Flujo de procesamiento del cliente

Reportar el resultado de la firma

Parámetros de solicitud

Ejemplo de solicitud

Respuesta correcta

Número de firmas

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