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

Ce document s'adresse aux développeurs ayant besoin d'intégrer directement les capacités de signature à distance et décrit les deux interfaces suivantes :

POST /v1/codesign/sign : soumettre le résumé de hachage à signer et obtenir le résultat de signature RSA PKCS#1.
POST /v1/codesign/report-sign : signaler 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 les adresses d'autres environnements, se référer à celles fournies par la livraison ou l'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'interface utilise l'authentification HTTP Basic :

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

Générer l'en-tête d'Authorization :

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

Structure de réponse générale

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

Champ	Type	Signification
`code`	integer	Code d’état métier. `0` indique un succès, toute autre valeur que `0` indique un échec métier.
`message`	string	Description de l’état métier, message d’erreur en cas d’échec.
`data`	object	Données métier de l’interface.

L’appelant doit traiter à la fois le code d’état HTTP et le code d’état métier :

HTTP non 2xx → traiter comme une erreur HTTP.
HTTP 2xx et code != 0 → traiter comme une 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 effectue une signature RSA PKCS#1 avec le certificat spécifié et renvoie le résultat.

Remarque

/v1/codesign/sign Un retour réussi du contenu signé est considéré comme une signature réussie, et le nombre de signatures est incrémenté de 1. Les requêtes échouées ne consomment pas de signature. L’appel ou non de 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 hachage à signer. L’appelant doit calculer le hachage localement selon le fichier cible et les exigences de l’outil de signature.
`algorithm`	string	Oui	Algorithme de hachage, prend en charge `SHA1`, `SHA256`, `SHA384`, `SHA512`.
`padding`	string	Oui	Mode de remplissage RSA, actuellement fixé à `PKCS1`.
`extra`	object	Non	Informations de contexte du client, utilisées pour l'enregistrement des signatures, l'audit et le dépannage.

Description des champs de extra :

Champ	Type	Signification
`platform`	string	Plateforme du client, par exemple `windows/amd64`, `linux/amd64`.
`version`	string	Version du client.
`revision`	string	Révision de la build du client.
`time`	string	Heure de build du client ou heure de la requête.
`hostname`	string	Nom d’hôte à l’origine de la signature.
`signing_filename`	string	Nom ou chemin du fichier signé, il est recommandé de le masquer conformément à 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 de succès

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

Champ	Type	Signification
`id`	string	ID de l’enregistrement de signature, utilisé lors de l’appel de `report-sign`.
`signature`	string	Encodage Base64 du résultat de la signature RSA.

Rapporter le résultat de la signature

Description de l’interface

POST /v1/codesign/report-sign

Après avoir obtenu le résultat de la signature à distance, le client peut échouer lors du traitement local, de l’écriture ou de la restitution à l’appelant. Cette interface est utilisée pour renvoyer l’état final du traitement du client au serveur, afin de faciliter l’affichage de l’enregistrement de signature et le dépannage d’audit.

Remarque

Cette interface enregistre uniquement le résultat du traitement côté client et ne modifie pas le résultat du comptage de /v1/codesign/sign. Ne pas appeler cette interface n’affecte pas le nombre de signatures réussies.

Paramètres de la demande

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

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

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
}

Exemple de réponse d’erreur

Échec d’authentification :

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

Erreur de paramètre :

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

Remarque

Les codes d’erreur et messages d’erreur spécifiques sont ceux réellement renvoyés par le serveur. La partie intégrante ne doit pas s’appuyer sur un texte d’erreur figé pour établir des branchements métier.

Recommandations d’intégration

Protégez soigneusement l’Access Secret, ne l’inscrivez pas dans les journaux, les rapports d’incident ou les pages frontend.
digest doit être l’encodage Base64 des octets bruts du hachage, ni une chaîne hexadécimale, ni le contenu complet du fichier.
algorithm doit correspondre à l’algorithme de hachage effectivement utilisé par digest.
Le mode de remplissage actuel est fixé à PKCS1, ne transmettez aucune autre valeur.
Les champs digest et signature peuvent être longs ; il est recommandé de ne journaliser que la longueur ou un résultat masqué du préfixe/suffixe.
Il est recommandé d’appeler report-sign pour signaler le résultat une fois le traitement final côté client terminé, afin de faciliter les audits 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 un délai d’expiration et une stratégie 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érale​

Interface de signature​

Description de l’interface​

Paramètres de la requête​

Exemple de requête​

Réponse de succès​

Rapporter le résultat de la signature​

Description de l’interface​

Paramètres de la demande​

Exemple de demande​

Réponse de succès​

Exemple de réponse d’erreur​

Recommandations d’intégration​

Adresse d'accès

Conventions générales

Format de la requête

Authentification

Structure de réponse générale

Interface de signature

Description de l’interface

Paramètres de la requête

Exemple de requête

Réponse de succès

Rapporter le résultat de la signature

Description de l’interface

Paramètres de la demande

Exemple de demande

Réponse de succès

Exemple de réponse d’erreur

Recommandations d’intégration