Référence API de signature de code à distance

Ce document s’adresse aux développeurs qui doivent intégrer directement la capacité de signature à distance et décrit les deux interfaces suivantes :

POST /v1/codesign/sign : soumettre le résumé haché à signer et obtenir le résultat de signature RSA PKCS#1.
POST /v1/codesign/report-sign : remonter le résultat final du traitement côté client (sans incidence sur le comptage des signatures).

Adresse d’accès

Environnement	Adresse
Environnement de production (par défaut)	`https://ssl.face.racent.com`
Environnement NICSRS	`https://ssl.face.nicsrs.com`

Pour d’autres adresses d’environnement, se référer à celles fournies par l’équipe de livraison ou d’exploitation.

Conventions générales

Format de la requête

Protocole : HTTPS
Méthode : POST
Corps : JSON
En-têtes :

Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

Authentification

L’API utilise l’authentification HTTP Basic Auth :

Nom d’utilisateur : Access Key
Mot de passe : Access Secret

Génération de l’en-tête Authorization :

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

Structure de réponse générique

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

Champ	Type	Signification
`code`	integer	Code de statut métier. `0` indique un succès, une valeur non `0` indique un échec métier.
`message`	string	Description du statut métier, correspondant à la description de l'erreur en cas d'échec.
`data`	object	Données métier de l'interface.

L'appelant doit traiter simultanément le code de statut HTTP et le code de statut métier :

HTTP non 2xx → traiter selon l'erreur HTTP.
HTTP 2xx et code != 0 → traiter selon l'erreur métier.
HTTP 2xx et code == 0 → lire le data correspondant.

Interface de signature

Description de l'interface

POST /v1/codesign/sign

Soumettez les octets bruts du hachage à signer (encodés en Base64) ; le service distant utilisera le certificat spécifié pour effectuer une signature RSA PKCS#1 et renverra le résultat.

Remarque

/v1/codesign/sign Un retour réussi du contenu de la signature est considéré comme une signature réussie, et le compteur de signatures augmente de 1. Une requête échouée ne consomme pas de tentative de signature. L’appel à report-sign n’affecte pas le comptage.

Paramètres de la 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
  }
}

Champ	Type	Requis	Signification
`code`	string	Oui	Numéro du certificat, utilisé pour sélectionner le certificat de signature à distance.
`digest`	string	Oui	Encodage Base64 des octets bruts du hash à signer. L’appelant doit calculer le hash localement selon le fichier cible et les exigences de l’outil de signature.
`algorithm`	string	Oui	Algorithme de hash, prend en charge `SHA1`, `SHA256`, `SHA384`, `SHA512`.
`padding`	string	Oui	Mode de remplissage RSA, actuellement fixé à `PKCS1`.
`extra`	object	Non	Informations contextuelles du client, utilisées pour l’enregistrement de signature, l’audit et le dépannage.

Description du champ extra :

Champ	Type	Signification
`platform`	string	Plateforme cliente, par exemple `windows/amd64`, `linux/amd64`.
`version`	string	Version du client.
`revision`	string	Révision de la build du client.
`time`	string	Heure de la build du client ou heure de la requête.
`hostname`	string	Nom d'hôte ayant initié la signature.
`signing_filename`	string	Nom ou chemin du fichier signé, recommandé de masquer selon la politique de sécurité.
`signing_filesize`	integer	Taille du fichier signé (en octets).

Exemple de requête

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

Réponse en cas de succès

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

字段	类型	含义
`id`	string	ID d’enregistrement de signature, utilisé lors de l’appel de `report-sign`.
`signature`	string	Encodage Base64 du résultat de la signature RSA.

Rapport du résultat de la signature

Description de l’interface

POST /v1/codesign/report-sign

Le client, après avoir obtenu le résultat de signature à distance, peut échouer lors du traitement local, de l'écriture ou de la restitution à l'appelant. Cette interface permet de renvoyer l'état final de traitement du client au serveur, afin de faciliter l'affichage des enregistrements de signature et l'audit.

Remarque

Cette interface ne fait qu'enregistrer le résultat de traitement côté client ; elle ne modifie pas le résultat de comptage de /v1/codesign/sign. Le fait de ne pas appeler cette interface n'affecte pas le nombre de signatures réussies.

Paramètres de la requête

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

Champ	Type	Requis	Signification
`id`	string	Oui	`/v1/codesign/sign` renvoyé par `data.id`.
`status`	integer	Oui	Statut final de traitement côté client : `1` succès, `2` échec.

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

响应 réussie

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

Erreur de réponse : exemple

Échec de l’authentification :

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

Paramètre invalide :

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

Attention

Les codes d'erreur et messages d'erreur précis dépendent de la réponse réelle du serveur. L'intégrateur ne doit pas s'appuyer sur des libellés d'erreur fixes pour la logique de branchement métier.

Recommandations d'intégration

Protégez correctement l'Access Secret, ne l'écrivez pas dans les journaux, les rapports de plantage ou les pages front-end.
digest doit être l'encodage Base64 des octets bruts du hash, pas une chaîne hexadécimale, ni le contenu complet du fichier.
algorithm doit correspondre à l'algorithme de hachage réel utilisé par digest.
Le mode de remplissage actuel est fixé à PKCS1, ne transmettez pas d'autre valeur.
Les champs digest et signature peuvent être longs, dans les journaux, il est recommandé d'enregistrer uniquement la longueur ou le résultat de masquage des préfixes/suffixes.
Il est recommandé d'appeler report-sign pour signaler le résultat après le traitement final côté client, afin de faciliter l'audit et le dépannage ultérieurs.
Traitez séparément les erreurs réseau, les erreurs HTTP et les erreurs métier, et définissez des délais d'expiration et des stratégies de nouvelle tentative raisonnables pour les requêtes signées.

Adresse d’accès​

Conventions générales​

Format de la requête​

Authentification​

Structure de réponse générique​

Interface de signature​

Description de l'interface​

Paramètres de la requête​

Exemple de requête​

Réponse en cas de succès​

Rapport du résultat de la signature​

Description de l’interface​

Paramètres de la requête​

Exemple de requête​

响应 réussie​

Erreur de réponse : exemple​

Recommandations d'intégration​

Adresse d’accès

Conventions générales

Format de la requête

Authentification

Structure de réponse générique

Interface de signature

Description de l'interface

Paramètres de la requête

Exemple de requête

Réponse en cas de succès

Rapport du résultat de la signature

Description de l’interface

Paramètres de la requête

Exemple de requête

响应 réussie

Erreur de réponse : exemple

Recommandations d'intégration