Referenz zur Remote-Codesignatur-API

Dieses Dokument richtet sich an Entwickler, die Remote-Signaturfähigkeiten direkt integrieren müssen, und beschreibt die folgenden zwei Schnittstellen:

POST /v1/codesign/sign: Übermittelt die zu signierende Hash-Digest und erhält das RSA-PKCS#1-Signaturergebnis.
POST /v1/codesign/report-sign: Meldet das endgültige Verarbeitungsergebnis des Clients zurück (hat keinen Einfluss auf die Signaturzählung).

Zugangsadresse

Umgebung	Adresse
Produktionsumgebung (Standard)	`https://ssl.face.racent.com`
NICSRS-Umgebung	`https://ssl.face.nicsrs.com`

Falls Adressen für andere Umgebungen benötigt werden, gilt die von der Bereitstellung oder dem Betrieb bereitgestellte Adresse.

Allgemeine Vereinbarungen

Anfrageformat

Protokoll: HTTPS
Methode: POST
Body: JSON
Headers:

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

Authentifizierung

Die Schnittstelle verwendet HTTP Basic Auth:

Benutzername: Access Key
Passwort: Access Secret

Authorization-Header generieren:

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

Allgemeine Antwortstruktur

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

Feld	Typ	Bedeutung
`code`	integer	Geschäftsstatuscode. `0` bedeutet Erfolg, nicht `0` bedeutet Geschäftsfehler.
`message`	string	Beschreibung des Geschäftsstatus, bei Fehler die Fehlerbeschreibung.
`data`	object	Geschäftsdaten der Schnittstelle.

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

HTTP nicht 2xx → als HTTP-Fehler behandeln.
HTTP 2xx und code != 0 → als Geschäftsfehler behandeln.
HTTP 2xx und code == 0 → die entsprechende data lesen.

Signaturschnittstelle

Schnittstellenbeschreibung

POST /v1/codesign/sign

Reichen Sie die zu signierenden Hash-Rohbytes (Base64-codiert) ein. Der Remote-Dienst führt die RSA-PKCS#1-Signatur mit dem angegebenen Zertifikat durch und gibt das Ergebnis zurück.

Hinweis

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

Anfrageparameter

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

Feld	Typ	Erforderlich	Bedeutung
`code`	string	Ja	Zertifikatsnummer, die zur Auswahl des Fernsignaturzertifikats dient.
`digest`	string	Ja	Base64-Kodierung der Originalbytes des zu signierenden Hashwerts. Der Aufrufer muss den Hash lokal gemäß den Anforderungen der Zieldatei und des Signaturwerkzeugs berechnen.
`algorithm`	string	Ja	Hashalgorithmus, unterstützt `SHA1`, `SHA256`, `SHA384`, `SHA512`.
`padding`	string	Ja	RSA-Füllmodus, derzeit fest auf `PKCS1`.
`extra`	object	Nein	Client-Kontextinformationen für Signaturaufzeichnung, Audits und Fehlerbehebung.

Felderläuterung zu extra:

Feld	Typ	Bedeutung
`platform`	string	Client-Plattform, z. B. `windows/amd64`, `linux/amd64`.
`version`	string	Client-Version.
`revision`	string	Client-Build-Revision.
`time`	string	Client-Build-Zeit oder Anfragezeit.
`hostname`	string	Hostname, der die Signatur initiiert.
`signing_filename`	string	Name oder Pfad der signierten Datei; Maskierung gemäß Sicherheitsrichtlinie empfohlen.
`signing_filesize`	integer	Größe der signierten Datei (Byte).

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

Erfolgsantwort

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

Feld	Typ	Bedeutung
`id`	string	Signaturdatensatz-ID, wird beim Aufruf von `report-sign` verwendet.
`signature`	string	Base64-Kodierung des RSA-Signaturergebnisses.

Signaturergebnis melden

Schnittstellenbeschreibung

POST /v1/codesign/report-sign

Der Client kann nach Erhalt des Remote-Signaturergebnisses bei der lokalen Verarbeitung, beim Schreiben oder bei der Rückgabe an den Aufrufer fehlschlagen. Diese Schnittstelle dient dazu, den endgültigen Verarbeitungsstatus des Clients an den Server zurückzumelden, um die Anzeige des Signaturdatensatzes und die Audit-Fehlerbehebung zu erleichtern.

Hinweis

Diese Schnittstelle protokolliert nur das Verarbeitungsergebnis des Clients und ändert nicht das Zählergebnis von /v1/codesign/sign. Das Nichtaufrufen dieser Schnittstelle hat keinen Einfluss auf die Anzahl erfolgreicher Signaturen.

Anfrageparameter

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

Feld	Typ	Pflicht	Bedeutung
`id`	string	Ja	Der von `/v1/codesign/sign` zurückgegebene `data.id`.
`status`	integer	Ja	Endgültiger Verarbeitungsstatus des Clients: `1` Erfolg, `2` Fehler.

Anfragebeispiel

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 eine Fehlerantwort

Authentifizierung fehlgeschlagen:

{
  "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 Antwort des Servers. Die Integrationsseite sollte sich nicht auf feste Fehlertexte für Geschäftslogik-Verzweigungen verlassen.

Empfehlungen für die Integration

Schützen Sie den Access Secret sorgfältig und schreiben Sie ihn nicht in Protokolle, Absturzberichte oder Frontend-Seiten.
digest muss die Base64-Kodierung der ursprünglichen Hash-Bytes sein, keine hexadezimale Zeichenfolge und auch nicht der vollständige Dateiinhalt.
algorithm muss mit dem tatsächlichen Hash-Algorithmus von digest übereinstimmen.
Der aktuelle Füllmodus verwendet fest PKCS1; übergeben Sie keine anderen Werte.
Die Felder digest und signature können relativ lang sein. In Protokollen wird empfohlen, nur die Länge oder das Ergebnis der Maskierung von Präfix und Suffix zu erfassen.
Es wird empfohlen, nach Abschluss der finalen Verarbeitung auf Client-Seite report-sign aufzurufen, um das Ergebnis zu melden und spätere Audits und Fehleranalysen zu erleichtern.
Behandeln Sie Netzwerkfehler, HTTP-Fehler und Geschäftsfehler getrennt und legen Sie für signierte Anfragen angemessene Timeout- und Wiederholungsrichtlinien fest.

Zugangsadresse​

Allgemeine Vereinbarungen​

Anfrageformat​

Authentifizierung​

Allgemeine Antwortstruktur​

Signaturschnittstelle​

Schnittstellenbeschreibung​

Anfrageparameter​

Anfragebeispiel​

Erfolgsantwort​

Signaturergebnis melden​

Schnittstellenbeschreibung​

Anfrageparameter​

Anfragebeispiel​

Erfolgreiche Antwort​

Beispiel für eine Fehlerantwort​

Empfehlungen für die Integration​

Zugangsadresse

Allgemeine Vereinbarungen

Anfrageformat

Authentifizierung

Allgemeine Antwortstruktur

Signaturschnittstelle

Schnittstellenbeschreibung

Anfrageparameter

Anfragebeispiel

Erfolgsantwort

Signaturergebnis melden

Schnittstellenbeschreibung

Anfrageparameter

Anfragebeispiel

Erfolgreiche Antwort

Beispiel für eine Fehlerantwort

Empfehlungen für die Integration