Intégration API

sslTrus fournit une API de signature de code à distance, destinée aux développeurs qui ont besoin de développer eux-mêmes des clients de signature, des systèmes de build ou d’autres programmes d’intégration de signature.

L’API reçoit le condensé du fichier calculé par le client, le service de signature de code à distance effectue la signature avec la clé privée en utilisant le certificat de signature de code spécifié, puis renvoie le résultat de la signature.

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 signature renvoyé dans le fichier cible ou la structure de signature.
Rapporter le résultat final du traitement côté client selon les besoins.

La clé privée de signature de code est toujours conservée dans le HSM en nuage et ne sera jamais renvoyé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

Interface de signature complète :

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

Interface de rapport des résultats :

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

Si l’environnement de production utilise une autre adresse de service, veuillez vous référer à l’adresse fournie par la livraison ou l’exploitation.

Authentification

L’API utilise l’authentification HTTP Basic.

Correspondance :

Username = Access Key
Password = Access Secret

En-têtes de la requête :

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 le fournir directement via le paramètre -u :

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret est une information d’identification sensible et ne doit pas être écrit dans le code source, les fichiers de configuration publics, les journaux ou les pages frontales.

Format de requête général

L’API utilise :

HTTPS
POST
JSON

En-têtes de requête :

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

Description des champs :

Champ	Type	Description
`code`	integer	Code de statut métier, `0` indique le succès
`message`	string	Statut ou message d’erreur
`data`	object	Données métier de l’interface

Le client doit vérifier à la fois le code de statut HTTP et le code de statut métier.

Il est recommandé de procéder comme suit :

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

Ne vous fiez pas uniquement au code HTTP 200 pour déterminer si la requête de signature a réussi.

Interface de signature

Interface :

POST /v1/codesign/sign

Cet interface est utilisé pour soumettre le résumé à signer et obtenir le résultat de la signature avec la 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
  }
}

Paramètres principaux :

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

Algorithme de condensé

Actuellement pris en charge :

SHA1
SHA256
SHA384
SHA512

Par exemple, avec SHA-256 :

{
  "algorithm": "SHA256"
}

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

Format du digest

digest doit être :

Octets bruts du hachage → Base64

Non :

文件内容 Base64

ni non plus :

十六进制哈希字符串

Par exemple, si un condensé SHA-256 fait 32 octets, ces 32 octets bruts doivent être encodés en Base64 avant d’être transmis à l’interface.

padding

Actuellement, la valeur fixe utilisée est :

PKCS1

C'est-à-dire :

{
  "padding": "PKCS1"
}

Ne renseignez pas d’autres méthodes de remplissage.

extra

extra est utilisé pour enregistrer le contexte client, les informations d’audit et faciliter le diagnostic.

Pris 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 à l’origine de la requête
`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 les masquer conformément à la politique de sécurité côté 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

Réponse signée

Réponse de succès :

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

Champs renvoyés :

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

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

data.signature

Si vous devez traiter localement puis signaler l’état final, vous devez également enregistrer :

data.id

Flux de traitement côté client

Flux typique :

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

À noter :

/v1/codesign/sign

Uniquement responsable de la signature de clé privée à distance de bas niveau.

La façon dont PE Authenticode, JAR, PDF ou d’autres formats de fichiers organisent la structure de signature est traitée par le client en fonction du format cible.

Rapport du résultat de signature

Interface :

POST /v1/codesign/report-sign

Après réception du résultat de signature à distance, le client peut encore rencontrer un échec lors des étapes suivantes, par exemple :

Échec de construction de la structure de signature finale.
Échec d'écriture du fichier cible.
Erreur de permissions sur le fichier local.
Exception lors du traitement ultérieur du 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
}

Paramètres :

Champ	Type	Obligatoire	Description
`id`	string	Oui	ID d’enregistrement de signature renvoyé par `/v1/codesign/sign`
`status`	integer	Oui	Statut final du traitement côté client

Valeurs de statut :

Statut	Description
`1`	Traitement final côté client réussi
`2`	Traitement final côté client échoué

Exemple de demande

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

Réponse de succès

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

Nombre de signatures

Le nombre de signatures API est déterminé selon la réussite ou non de l’opération de signature à distance.

Lorsque :

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

Lorsque toutes les conditions sont remplies simultanément, la signature est considérée comme réussie :

签名次数 +1

Les cas suivants ne consomment pas de quota de signatures :

Échec de l’authentification.
Erreurs de paramètres.
Échec de la requête réseau.
Échec de la requête métier.
Le serveur n’a pas renvoyé le contenu de signature avec succès.

À noter tout particulièrement :

/v1/codesign/report-sign

Il s'agit uniquement de rapporter l'état de traitement final 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, mais qu'une erreur survient ensuite lors de l'écriture locale du fichier, la signature par clé privée à distance réalisée avec succès précédemment aura quand même consommé une signature.

Pour plus de règles de comptage, veuillez consulter les documents 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 côté client.

Échec d'authentification

Par exemple :

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

À vérifier :

L’Access Key est-elle correcte ?
L’Access Secret est-il correct ?
La requête contient-elle correctement l’en-tête Authorization ?

Erreur de paramètre

Par exemple :

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

Points à vérifier en priorité :

code est-il correct.
digest est-il un Base64 valide.
algorithm est-il cohérent avec le résumé.
padding est-il PKCS1.

Le client ne doit pas dépendre d'éléments fixes :

message

Les chaînes exécutent la logique du programme.

Le traitement métier doit se baser en priorité sur les codes d’état et le contrat d’interface.

Délais d’attente et nouvelles tentatives

Lors de l’appel à l’interface de signature à distance, il convient de définir un délai d’attente réseau raisonnable.

Lorsqu’une nouvelle tentative est nécessaire, il faut particulièrement veiller à :

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

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 reprise automatique, il convient d’éviter de relancer indéfiniment ou sans condition la demande 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 renvoyé.
Le statut de traitement final côté client.

Ne consignez pas le secret d’accès complet 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

Pour ce type de données volumineuses, il n’est pas recommandé de les écrire intégralement dans les journaux ordinaires.

Vous pouvez 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 de répertoire interne. Il convient de décider s’il faut le masquer selon les exigences de sécurité réelles.

Consignes de sécurité

Lors de l’intégration de l’API, il est recommandé de suivre les principes suivants :

L’Access Secret ne doit pas être enregistré dans le code front-end.
L’Access Secret ne doit pas être commité dans un dépôt Git.
Ne pas enregistrer l’en-tête Authorization complet dans les journaux ordinaires.
Ne pas enregistrer l’Access Secret complet.
Masquer digest et signature dans les journaux si nécessaire.
Appeler le service de signature à distance via HTTPS.
Le client doit vérifier l’état HTTP et l’état métier.
Définir des délais d’attente 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 signature, et non la clé privée.

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

Quand utiliser l’API

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

Scénario	Méthode recommandée
Signer directement des fichiers EXE, DLL, MSI, etc.	Outil client
Microsoft SignTool, Visual Studio et autres logiciels Windows	Windows Provider
Signature de fichiers JAR	Intégration Java
Builds automatisés GitHub Actions, Electron Builder, etc.	CI/CD et outils de build
Développer soi-même un client de signature	API
Implémenter soi-même le flux de signature de format de fichier	API
Besoin de contrôler directement le digest et le résultat de signature	API

L’API convient mieux aux développeurs qui ont besoin de contrôler le flux de signature de bas niveau.

S’il suffit de signer des fichiers ordinaires, privilégier les clients existants ou les Providers standard permet de réduire le travail lié à la gestion soi-même du format de fichier de signature.

Adresse d’accès​

Authentification​

Format de requête général​

Format de réponse général​

Interface de signature​

Paramètres de la requête​

Algorithme de condensé​

Format du digest​

padding​

extra​

Exemple de demande de signature​

Réponse signée​

Flux de traitement côté client​

Rapport du résultat de signature​

Paramètres de la requête​

Exemple de demande​

Réponse de succès​

Nombre de signatures​

Gestion des erreurs​

Échec d'authentification​

Erreur de paramètre​

Délais d’attente et nouvelles tentatives​

Journaux et audit​

Consignes de sécurité​

Quand utiliser l’API​

Adresse d’accès

Authentification

Format de requête général

Format de réponse général

Interface de signature

Paramètres de la requête

Algorithme de condensé

Format du digest

padding

extra

Exemple de demande de signature

Réponse signée

Flux de traitement côté client

Rapport du résultat de signature

Paramètres de la requête

Exemple de demande

Réponse de succès

Nombre de signatures

Gestion des erreurs

Échec d'authentification

Erreur de paramètre

Délais d’attente et nouvelles tentatives

Journaux et audit

Consignes de sécurité

Quand utiliser l’API