Intégration API

sslTrus propose une API de signature de code à distance, destinée aux développeurs qui doivent développer leur propre client de signature, leur système de build ou d’autres programmes d’intégration de signature.

L’API reçoit le condensé (hash) du fichier calculé côté client, puis le service de signature de code à distance utilise le certificat de signature de code spécifié pour effectuer la signature avec la clé privée, et renvoie le résultat de la signature au client.

Le client est responsable de :

Calculer le condensé des données à signer.
Construire la structure de signature requise pour le fichier cible.
Appeler l’interface de signature à distance.
Écrire le résultat de la signature retourné dans le fichier cible ou la structure de signature.
Rapporter le résultat final du traitement du client si nécessaire.

La clé privée de signature de code est toujours conservée dans un HSM cloud et n’est jamais retournée au client via l’API.

Adresse d’accès

Adresse par défaut de l’environnement de production :

https://ssl.face.racent.com

Environnement NICSRS :

https://ssl.face.nicsrs.com

完整签名接口：

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

接口 de rapport de résultats :

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

Si l'environnement de livraison réel utilise d'autres adresses de service, veuillez vous référer aux adresses fournies par l'équipe de livraison ou d'exploitation.

Authentification

L'API utilise l'authentification HTTP Basic.

Correspondance :

Username = Access Key
Password = Access Secret

请求头 :

Authorization: Basic <base64(accessKey:accessSecret)>

Par exemple :

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

Lors de l’utilisation réelle de curl, vous pouvez directement fournir le paramètre -u :

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret 属于敏感凭证，不应写入源代码、公开配置文件、日志或前端页面。

Format général des requêtes

L'API utilise :

HTTPS
POST
JSON

Voici les en-têtes :

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

Format de réponse général

L’API renvoie une structure JSON unifiée :

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

Champ	Type	Description
`code`	integer	Code d'état métier, `0` indique un succès
`message`	string	Message d'état ou d'erreur
`data`	object	Données métier de l'interface

Le client doit vérifier simultanément le code d'état HTTP et le code d'état métier.

Il est recommandé de procéder de la manière suivante :

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

Ne vous fiez pas uniquement au code HTTP 200 pour considérer qu’une requête signée a réussi.

Interface de signature

Interface :

POST /v1/codesign/sign

Cette interface est utilisée pour soumettre un résumé à signer et obtenir le résultat de signature par clé privée distante.

Paramètres de la requête

Exemple de requête :

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

Principaux paramètres :

Paramètre	Type	Obligatoire	Description
`code`	string	Oui	Numéro du certificat de signature de code
`digest`	string	Oui	Encodage Base64 des octets bruts du résumé à signer
`algorithm`	string	Oui	Algorithme de résumé
`padding`	string	Oui	Mode de remplissage RSA, actuellement fixé à `PKCS1`
`extra`	object	Non	Contexte du client et informations d’audit

Algorithme de résumé

Actuellement pris en charge :

SHA1
SHA256

Par exemple, lors de l’utilisation de SHA-256 :

{
  "algorithm": "SHA256"
}

algorithm doit être cohérent avec l’algorithme de résumé effectivement utilisé par digest.

Format digest

digest doit être :

Hash des octets bruts → Base64

不是：

文件内容 Base64

Ce n’est pas non plus :

十六进制哈希字符串

Par exemple, si un résumé SHA-256 a lui-même une taille de 32 octets, ces 32 octets bruts doivent être encodés en Base64 avant d’être transmis à l’interface.

padding

Actuellement, la valeur suivante est utilisée en permanence :

PKCS1

即 :

{
  "padding": "PKCS1"
}

extra

extra est utilisé pour enregistrer le contexte du client, les informations d'audit et faciliter le dépannage.

Prise en charge :

Champ	Type	Description
`platform`	string	Plateforme cliente
`version`	string	Version du client
`revision`	string	Révision de build du client
`time`	string	Heure de build ou heure d'enregistrement côté requête
`hostname`	string	Nom d'hôte de la requête d'origine
`signing_filename`	string	Nom du fichier signé ou chemin local
`signing_filesize`	integer	Taille du fichier, en octets

Par exemple :

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

Si signing_filename contient des répertoires internes, des noms d’utilisateur ou d’autres informations sensibles, il est recommandé de procéder à une désensibilisation conformément à la politique de sécurité du client.

Exemple de demande de signature

Utilisation de 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

Signature de la réponse

Réponse en cas de succès :

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

返回字段：

字段	Type	Description
`id`	string	ID de l’enregistrement de signature
`signature`	string	Encodage Base64 du résultat de signature RSA

Pour la capacité de signature réelle, le client utilise principalement :

data.signature

Si une remontée du statut final doit être effectuée après le traitement local, il est également nécessaire de conserver :

data.id

Flux de traitement côté client

Processus typique :

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

Voici la traduction en français du fragment fourni :

Il convient de noter :

/v1/codesign/sign

Uniquement responsable de la signature avec la clé privée distante au niveau du socle.

La manière dont PE Authenticode, JAR, PDF ou d'autres formats de fichiers organisent la structure de signature est gérée par le client lui-même en fonction du format cible.

Rapport du résultat de signature

Interface :

POST /v1/codesign/report-sign

Une fois que le client a reçu le résultat de la signature à distance, des échecs peuvent encore survenir au cours des étapes suivantes, par exemple :

Échec de la construction de la structure de signature finale.
Échec de l’écriture du fichier cible.
Erreur de permission sur le fichier local.
Anomalie dans le traitement ultérieur côté client.

Vous pouvez utiliser cette interface pour renvoyer l’état final du traitement au serveur.

Paramètres de la requête

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

参数 :

字段	类型	必填	说明
`id`	string	是	`/v1/codesign/sign` 返回的签名记录 ID
`status`	integer	是	客户端最终处理状态

状态值 :

状态	说明
`1`	客户端最终处理成功
`2`	客户端最终处理失败

Exemple de requête

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

成功响应

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

Nombre de signatures

Le nombre de signatures via l'API est déterminé par la réussite de l'opération de signature à distance.

Lorsque :

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

Lorsque les deux conditions sont réunies, cela est considéré comme une signature réussie :

签名次数 +1

Les situations suivantes ne consomment pas de quota de signature :

Échec d'authentification.
Erreur de paramètre.
Échec de la requête réseau.
Échec de la requête métier.
Le serveur ne renvoie pas correctement le contenu de la signature.

Points particuliers à noter :

/v1/codesign/report-sign

Il s’agit uniquement de remonter l’état final du traitement côté client ; cela ne constitue pas une nouvelle opération de signature et n’augmente ni ne diminue le nombre de signatures.

Même si le client a déjà obtenu avec succès le résultat de la signature à distance, si l’écriture locale du fichier échoue ensuite, la signature privée à distance précédemment effectuée avec succès compte toujours comme une occurrence de signature.

Pour plus de règles de comptage, veuillez consulter la documentation de référence.

Gestion des erreurs

Le client doit traiter séparément :

Les erreurs réseau.
Les erreurs HTTP.
Les erreurs métier de l’API.
Les erreurs de traitement local du client.

Échec d’authentification

Par exemple :

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

Vérifier que :

La Access Key est correcte.
La Access Secret est correcte.
La requête transporte correctement l’en-tête Authorization.

Erreur de paramètre

Par exemple :

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

Points de contrôle prioritaires :

Vérifier si code est correct.
Confirmer que digest est un Base64 valide.
S'assurer que algorithm correspond au résumé.
Vérifier que padding est bien PKCS1.

Le client ne doit pas dépendre d'une valeur fixe :

message

Chaîne de caractères exécutant la logique du programme.

Le traitement métier doit donner la priorité au code de statut et au contrat de l'interface.

Délai d'expiration et nouvelle tentative

Lors de l'appel à une interface de signature à distance, un délai d'expiration réseau raisonnable doit être défini.

En cas de nouvelle tentative, une attention particulière doit être portée à :

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

Si le client ne reçoit pas de réponse en raison d’une anomalie réseau, cela ne signifie pas nécessairement que le serveur n’a pas terminé la signature.

Par conséquent, lors de la conception d’un mécanisme de nouvelle tentative automatique, il convient d’éviter de relancer de manière illimitée ou inconditionnelle les demandes de signature.

Il est recommandé d’enregistrer séparément :

L’heure de début de la demande.
Le numéro du certificat cible.
L’identifiant du résumé.
Le statut HTTP.
Le code de statut métier.
L’ID d’enregistrement de signature retourné.
L’état de traitement final côté client.

Ne pas consigner la clé d’accès secrète complète dans les journaux.

Journaux et audit

Il est recommandé d’enregistrer le contexte de signature nécessaire, par exemple :

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

Pour :

digest
signature

Ces données de grande taille ne doivent pas être intégralement consignées dans les journaux ordinaires.

Il est possible d'enregistrer :

La longueur.
Le hachage.
Les préfixes et suffixes après masquage.

Le chemin du fichier peut également contenir un nom d'utilisateur, un nom de projet ou des informations sur des répertoires internes ; il convient de décider, selon les exigences de sécurité réelles, s'il doit être masqué.

Consignes de sécurité

Lors de l'intégration de l'API, il est recommandé de respecter les principes suivants :

L'Access Secret ne doit pas être stocké dans le code front-end.
L'Access Secret ne doit pas être soumis à un dépôt Git.
Ne pas consigner l'intégralité de l'en-tête Authorization dans les journaux ordinaires.
Ne pas enregistrer l'intégralité de l'Access Secret.
Appliquer un masquage nécessaire dans les journaux pour digest et signature.
Appeler le service de signature distant via HTTPS.
Le client doit vérifier le statut HTTP et le statut métier.
Définir des délais d'expiration et des stratégies de nouvelle tentative raisonnables pour les requêtes réseau.

L'API de signature de code à distance renvoie le résultat de la signature, et non la clé privée.

La clé privée de signature de code reste toujours conservée dans le HSM distant.

Quand utiliser l'API

Si le mode d'intégration existant répond déjà aux besoins, il est généralement possible d'utiliser directement l'outil correspondant.

Scénario	Méthode recommandée
Signature directe de fichiers EXE, DLL, MSI, etc.	Outil client
Logiciels Windows tels que Microsoft SignTool, Visual Studio, etc.	Provider Windows
Signature de fichiers JAR	Intégration Java
Constructions automatisées telles que GitHub Actions, Electron Builder, etc.	Outils CI/CD et de construction
Développement d'un client de signature personnalisé	API
Mise en œuvre personnalisée du flux de signature de formats de fichiers	API
Nécessité de contrôler directement le condensé et le résultat de la signature	API

L'API convient mieux aux développeurs qui doivent contrôler le processus de signature sous-jacent.

Si vous devez simplement effectuer une signature de code pour des fichiers ordinaires, privilégier un client existant ou un Provider standard peut réduire la charge de travail liée au traitement du format de fichier de signature.

Adresse d’accès​

Authentification​

Format général des requêtes​

Format de réponse général​

Interface de signature​

Paramètres de la requête​

Algorithme de résumé​

Format digest​

padding​

extra​

Exemple de demande de signature​

Signature de la réponse​

Flux de traitement côté client​

Rapport du résultat de signature​

Paramètres de la requête​

Exemple de requête​

成功响应​

Nombre de signatures​

Gestion des erreurs​

Échec d’authentification​

Erreur de paramètre​

Délai d'expiration et nouvelle tentative​

Journaux et audit​

Consignes de sécurité​

Quand utiliser l'API​

Adresse d’accès

Authentification

Format général des requêtes

Format de réponse général

Interface de signature

Paramètres de la requête

Algorithme de résumé

Format digest

padding

extra

Exemple de demande de signature

Signature de la réponse

Flux de traitement côté client

Rapport du résultat de signature

Paramètres de la requête

Exemple de requête

成功响应

Nombre de signatures

Gestion des erreurs

Échec d’authentification

Erreur de paramètre

Délai d'expiration et nouvelle tentative

Journaux et audit

Consignes de sécurité

Quand utiliser l'API