Zum Hauptinhalt springen

API-Referenz für Remote-Codesignatur

Dieser Artikel richtet sich an Entwickler, die Remote-Signaturfunktionen direkt integrieren müssen, und beschreibt die folgenden zwei Schnittstellen:

  • POST /v1/codesign/sign：Übermitteln Sie den zu signierenden Hash-Digest und erhalten Sie das RSA PKCS#1-Signaturergebnis.
  • POST /v1/codesign/report-sign：Melden Sie das endgültige Verarbeitungsergebnis des Clients (ohne Auswirkung auf die Signaturzählung).

Zugriffsadresse​

UmgebungAdresse
Produktionsumgebung (Standard)https://ssl.face.racent.com
NICSRS-Umgebunghttps://ssl.face.nicsrs.com

Für Adressen anderer Umgebungen gelten die von der Lieferung oder dem Betrieb bereitgestellten Adressen.

Allgemeine Konventionen​

Anforderungsformat​

  • Protokoll: HTTPS
  • Methode: POST
  • Body: JSON
  • Header:
Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

鉴权​

Die Schnittstelle verwendet HTTP Basic Auth:

  • Benutzername: Access Key
  • Passwort: Access Secret

Erzeugen des Authorization-Headers:

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

Allgemeine Antwortstruktur​

{
  "code": 0,
  "message": "ok",
  "data": {}
}
FeldTypBedeutung
codeintegerGeschäftsstatuscode. 0 bedeutet Erfolg, nicht 0 bedeutet Geschäftsf ehler.
messagestringGeschäftsstatusbeschreibung, bei Fehler die Fehlerbeschreibung.
dataobjectSchnittstellengeschäftsdaten.

Der Aufrufer sollte sowohl den HTTP-Statuscode als auch den Geschäftsstatuscode verarbeiten:

  • HTTP nicht 2xx → gemäß HTTP-Fehler behandeln.
  • HTTP 2xx und code != 0 → gemäß Geschäftsf ehler behandeln.
  • HTTP 2xx und code == 0 → das entsprechende data lesen.

Signaturschnittstelle​

Schnittstellenbeschreibung​

POST /v1/codesign/sign

Übermitteln Sie die Rohbytes des zu signierenden Hashs (Base64-kodiert). Der Remote-Dienst führt die RSA-PKCS#1-Signatur mit dem angegebenen Zertifikat aus und gibt das Ergebnis zurück.

Hinweis

/v1/codesign/sign Eine erfolgreiche Rückgabe des Signaturinhalts gilt als erfolgreiche Signatur, und die Signaturanzahl wird um 1 erhöht. Fehlgeschlagene Anfragen verbrauchen keine Signaturanzahl. Ob report-sign aufgerufen wird, hat keinen Einfluss auf die Zählung.

Anforderungsparameter​

{
  "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
  }
}
FeldTypErforderlichBedeutung
codestringJaZertifikatsnummer, zur Auswahl des remote-Signaturzertifikats.
digeststringJaBase64-Kodierung der Original-Bytes des zu signierenden Hashs. Der Aufrufer muss den Hash lokal gemäß den Anforderungen der Zieldatei und des Signaturtools berechnen.
algorithmstringJaHash-Algorithmus, unterstützt SHA1, SHA256, SHA384, SHA512.
paddingstringJaRSA-Paddungsmodus, derzeit festgelegt auf PKCS1.
extraobjectNeinKontextinformationen des Clients, verwendet für Signaturaufzeichnungen, Prüfung und Fehlerbehebung.

Feldbeschreibung für extra:

FeldTypBedeutung
platformstringClient-Plattform, z. B. windows/amd64, linux/amd64.
versionstringClient-Version.
revisionstringRevisions-ID der Client-Konstruktion.
timestringZeitpunkt der Client-Konstruktion oder der Anfrage.
hostnamestringHostname, von dem die Signatur initiiert wurde.
signing_filenamestringDateiname oder Pfad der signierten Datei, Empfehlung zur Maskierung gemäß Sicherheitsrichtlinien.
signing_filesizeintegerGröße der signierten Datei (Bytes).

Anfragebeispiel​

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

Erfolgreiche Antwort​

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "735985894427246592",
    "signature": "BASE64_ENCODED_SIGNATURE"
  }
}
字段类型含义
idstringID des Signaturdatensatzes, verwendet beim Aufruf von report-sign.
signaturestringBase64-Kodierung des RSA-Signaturergebnisses.

Meldung des Signaturergebnisses​

Schnittstellenbeschreibung​

POST /v1/codesign/report-sign

Der Client kann nach dem Erhalt des Remote-Signaturergebnisses beim lokalen Verarbeiten, Schreiben oder Zurückgeben an den Aufrufer fehlschlagen. Diese Schnittstelle dient dazu, den endgültigen Verarbeitungsstatus des Clients an den Server zurückzumelden, um die Anzeige von Signaturaufzeichnungen und die Prüfung zu erleichtern.

Hinweis

Diese Schnittstelle protokolliert nur das Verarbeitungsergebnis des Clients und ändert nicht das Zählungsergebnis von /v1/codesign/sign. Das Aufrufen dieser Schnittstelle beeinflusst nicht die Anzahl erfolgreicher Signaturen.

Anfrageparameter​

{
  "id": "735985894427246592",
  "status": 1
}
FeldTyperforderlichBedeutung
idstringjaDas von /v1/codesign/sign zurückgegebene data.id.
statusintegerjaEndgültiger Verarbeitungsstatus des Clients: 1 erfolgreich, 2 fehlgeschlagen.

Beispiel für eine Anfrage​

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

Erfolgreiche Antwort​

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

Beispiel für Fehlerantworten​

Authentifizierungsfehler:

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

Parameterfehler:

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

Die konkreten Fehlercodes und Fehlermeldungen richten sich nach der tatsächlichen Serverantwort. Integrationen sollten sich nicht auf feste Fehlertexte für Geschäftslogik-Verzweigungen verlassen.

Integrationsempfehlungen​

  • Bewahren Sie das Access Secret sorgfältig auf und schreiben Sie es nicht in Logs, Absturzberichte oder Frontend-Seiten.
  • digest muss die Base64-Kodierung der rohen Hash-Bytes sein, kein Hexadezimal-String und auch nicht der vollständige Dateiinhalt.
  • algorithm muss mit dem tatsächlichen Hash-Algorithmus von digest übereinstimmen.
  • Das aktuelle Padding-Verfahren ist fest auf PKCS1 eingestellt; übergeben Sie keine anderen Werte.
  • Die Felder digest und signature können lang sein; in Logs wird empfohlen, nur die Länge oder ein maskiertes Präfix/Suffix zu protokollieren.
  • Es wird empfohlen, nach Abschluss der finalen Verarbeitung auf Clientseite das Ergebnis über report-sign zu melden, um spätere Prüfungen und Fehleranalysen zu erleichtern.
  • Behandeln Sie Netzwerkfehler, HTTP-Fehler und Geschäftsfehler getrennt und legen Sie für Signaturanfragen angemessene Timeout- und Wiederholungsstrategien fest.
Letztes Update am