API-Integration

sslTrus bietet eine Remote-API für Codesignatur an, die sich an Entwickler richtet, die eigene Signatur-Clients, Build-Systeme oder andere Signatur-Integrationsprogramme entwickeln müssen.

Die API empfängt den vom Client berechneten Datei-Hash, der Remote-Codesignaturdienst verwendet das angegebene Codesignaturzertifikat für die private Schlüsselsignatur und gibt das Signaturergebnis zurück.

Der Client ist verantwortlich für:

Die Berechnung des Hashs der zu signierenden Daten.
Den Aufbau der für die Zieldatei erforderlichen Signaturstruktur.
Den Aufruf der Remote-Signaturschnittstelle.
Das Schreiben des zurückgegebenen Signaturergebnisses in die Zieldatei oder die Signaturstruktur.
Das Melden des endgültigen Verarbeitungsergebnisses des Clients bei Bedarf.

Der private Codesignaturschlüssel wird stets in der Cloud-HSM gespeichert und wird nicht über die API an den Client zurückgegeben.

Zugangsadresse

Standardadresse in der Produktionsumgebung:

https://ssl.face.racent.com

NICSRS-Umgebung:

https://ssl.face.nicsrs.com

Vollständiger Signatur-API-Endpunkt:

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

Ergebnis-Melde-Schnittstelle:

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

Wenn die tatsächliche Bereitstellungsumgebung eine andere Serviceadresse verwendet, richten Sie sich bitte nach der von Bereitstellung oder Betrieb bereitgestellten Adresse.

Identitätsauthentifizierung

Die API verwendet HTTP Basic Auth.

Entsprechung:

Username = Access Key
Password = Access Secret

Anfrage-Header:

Authorization: Basic <base64(accessKey:accessSecret)>

Beispiel:

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

Bei der tatsächlichen Verwendung von curl kann dieser direkt über den Parameter -u bereitgestellt werden:

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret ist eine vertrauliche Zugangsinformation und darf nicht in Quellcode, öffentliche Konfigurationsdateien, Protokolle oder Frontend-Seiten geschrieben werden.

Allgemeines Anfrageformat

Die API verwendet:

HTTPS
POST
JSON

Anfrage-Header (Request Header):
Anfrage-Header enthalten Metadaten einer HTTP-Anfrage und übermitteln dem Server zusätzliche Angaben wie den Clienttyp, unterstützte Inhaltsformate oder Authentifizierungsinformationen.

Content-Type: application/json
Accept: application/json
Authorization: Basic <credentials>

Allgemeines Antwortformat

Die API gibt eine einheitliche JSON-Struktur zurück:

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

Feldbeschreibung:

Feld	Typ	Beschreibung
`code`	integer	Geschäftlicher Statuscode, `0` bedeutet Erfolg
`message`	string	Status- oder Fehlerinformation
`data`	object	Geschäftsdaten der Schnittstelle

Der Client muss gleichzeitig den HTTP-Statuscode und den geschäftlichen Statuscode prüfen.

Es wird empfohlen, wie folgt vorzugehen:

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

Verlassen Sie sich nicht nur auf HTTP 200, um den Erfolg einer Signieranfrage zu beurteilen.

Signaturschnittstelle

Schnittstelle:

POST /v1/codesign/sign

Diese Schnittstelle dient zum Einreichen einer zu signierenden Zusammenfassung und zum Abrufen des Signierergebnisses mit dem entfernten privaten Schlüssel.

Anfrageparameter

Anfragebeispiel:

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

Wichtige Parameter:

Parameter	Typ	Erforderlich	Beschreibung
`code`	string	Ja	Code-Signing-Zertifikatsnummer
`digest`	string	Ja	Base64-Kodierung der ursprünglichen Rohbytes der zu signierenden Zusammenfassung
`algorithm`	string	Ja	Zusammenfassungsalgorithmus
`padding`	string	Ja	RSA-Padding-Methode, derzeit festgelegt auf `PKCS1`
`extra`	object	Nein	Clientkontext- und Auditinformationen

Zusammenfassungsalgorithmus

Derzeit unterstützt:

SHA1
SHA256

Zum Beispiel bei Verwendung von SHA-256:

{
  "algorithm": "SHA256"
}

algorithm muss mit dem tatsächlich verwendeten Digest-Algorithmus von digest übereinstimmen.

digest-Format

digest muss folgendes sein:

Hash der Rohbytes → Base64

Nicht:

文件内容 Base64

Auch nicht:

十六进制哈希字符串

Zum Beispiel sollte ein SHA-256-Digest selbst 32 Byte umfassen; diese 32 Rohbytes müssen dann Base64-codiert und an die API übergeben werden.

Padding

Derzeit wird fest Folgendes verwendet:

PKCS1

Das heißt:

{
  "padding": "PKCS1"
}

extra

extra wird verwendet, um den Client-Kontext, Audit-Informationen zu erfassen und die Fehlerbehebung zu unterstützen.

Unterstützt:

Feld	Typ	Beschreibung
`platform`	string	Client-Plattform
`version`	string	Client-Version
`revision`	string	Build-Revision des Clients
`time`	string	Build-Zeit oder von der Anfrageseite erfasste Zeit
`hostname`	string	Hostname, von dem die Anfrage initiiert wurde
`signing_filename`	string	Signierter Dateiname oder lokaler Pfad
`signing_filesize`	integer	Dateigröße in Bytes

Zum Beispiel:

{
  "extra": {
    "platform": "linux/amd64",
    "version": "1.2.0",
    "hostname": "github-runner-01",
    "signing_filename": "app.exe",
    "signing_filesize": 5242880
  }
}

Wenn signing_filename interne Verzeichnisse, Benutzernamen oder andere sensible Informationen enthält, wird empfohlen, diese gemäß den Sicherheitsrichtlinien des Kunden zu anonymisieren.

Beispiel für eine Signieranfrage

Verwendung von 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

Signaturantwort

Erfolgreiche Antwort:

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

Feld	Typ	Beschreibung
`id`	string	ID des Signaturdatensatzes
`signature`	string	Base64-Kodierung des RSA-Signaturergebnisses

Für die tatsächliche Signaturfunktion verwendet der Client hauptsächlich:

data.signature

Wenn die Verarbeitung lokal abgeschlossen ist und der endgültige Status gemeldet werden muss, muss zusätzlich Folgendes gespeichert werden:

data.id

Client-Verarbeitungsablauf

Typischer Ablauf:

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

Zu beachten:

/v1/codesign/sign

Nur für die Signierung mit dem entfernten privaten Schlüssel auf der unteren Ebene zuständig.

Wie PE Authenticode, JAR, PDF oder andere Dateiformate die Signaturstruktur organisieren, wird vom Client gemäß dem Zielformat selbst behandelt.

Signaturergebnis melden

Schnittstelle:

POST /v1/codesign/report-sign

Der Client kann nach Erhalt des Ergebnisses der Remote-Signatur weiterhin in nachfolgenden Prozessen Fehler aufweisen, zum Beispiel:

Fehler beim Aufbau der endgültigen Signaturstruktur.
Fehler beim Schreiben in die Zieldatei.
Fehler bei lokalen Dateiberechtigungen.
Anomalien in der nachfolgenden Client-Verarbeitung.

Über diese Schnittstelle kann der endgültige Verarbeitungsstatus an den Server zurückgemeldet werden.

Anforderungsparameter

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

Parameter:

Feld	Typ	Erforderlich	Beschreibung
`id`	string	Ja	Von `/v1/codesign/sign` zurückgegebene Signaturdatensatz-ID
`status`	integer	Ja	Endgültiger Verarbeitungsstatus des Clients

Statuswerte：

Status	Beschreibung
`1`	Endgültige Verarbeitung des Clients erfolgreich
`2`	Endgültige Verarbeitung des Clients fehlgeschlagen

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
}

Signaturanzahl

Die Anzahl der API-Signaturen richtet sich danach, ob der Remote-Signiervorgang erfolgreich war.

Wenn:

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

Gleichzeitig erfüllt, gilt als eine erfolgreiche Signatur:

签名次数 +1

Die folgenden Fälle verbrauchen keine Signaturanzahl:

Authentifizierungsfehler.
Parameterfehler.
Netzwerkfehler bei der Anfrage.
Fehler bei der Geschäftsanfrage.
Der Server hat den Signaturinhalt nicht erfolgreich zurückgegeben.

Besonders zu beachten ist:

/v1/codesign/report-sign

Nur die Übermittlung des endgültigen Verarbeitungsstatus durch den Client, stellt keine neue Signaturoperation dar und erhöht oder verringert auch nicht die Anzahl der Signaturen.

Selbst wenn der Client das Ergebnis der Remote-Signatur erfolgreich erhalten hat, aber anschließend beim lokalen Schreiben in die Datei ein Fehler auftritt, wurde die zuvor erfolgreich abgeschlossene Remote-Signatur mit dem privaten Schlüssel bereits einmal als Signatur gezählt.

Weitere Regeln zur Signaturzählung finden Sie in den Referenzmaterialien.

Fehlerbehandlung

Der Client sollte Folgendes separat behandeln:

Netzwerkfehler.
HTTP-Fehler.
API-Geschäftsfehler.
Lokale Verarbeitungsfehler des Clients.

Fehler bei der Authentifizierung

Zum Beispiel:

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

Zu überprüfen:

Ob der Access Key korrekt ist.
Ob das Access Secret korrekt ist.
Ob die Anfrage den Authorization Header korrekt enthält.

Parameterfehler

Zum Beispiel:

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

Es ist besonders wichtig, Folgendes zu prüfen:

Ob code korrekt ist.
Ob digest ein korrektes Base64 ist.
Ob algorithm mit der Zusammenfassung übereinstimmt.
Ob padding PKCS1 ist.

Der Client sollte sich nicht auf feste Werte verlassen:

message

String-Ausführungsprogrammlogik.

Die Geschäftsverarbeitung sollte sich in erster Linie auf den Statuscode und den API-Vertrag stützen.

Timeout und Wiederholung

Beim Aufruf einer Remote-Signaturschnittstelle sollte ein angemessenes Netzwerk-Timeout festgelegt werden.

Wenn eine Wiederholung erforderlich ist, sollte besonders beachtet werden:

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

Wenn der Client aufgrund eines Netzwerkfehlers keine Antwort erhält, bedeutet das nicht zwangsläufig, dass der Server die Signierung nicht abgeschlossen hat.

Daher sollte bei der Gestaltung des automatischen Wiederholungsmechanismus vermieden werden, Signaturanfragen unbegrenzt oder ohne Bedingungen erneut zu senden.

Es wird empfohlen, Folgendes jeweils zu protokollieren:

Startzeitpunkt der Anfrage.
Ziel-Zertifikatsnummer.
Zusammenfassungskennung.
HTTP-Status.
Geschäftsstatuscode.
Zurückgegebene Signaturdatensatz-ID.
Endgültiger Verarbeitungsstatus des Clients.

Der vollständige Access Secret darf nicht im Log protokolliert werden.

Protokollierung und Prüfung

Es wird empfohlen, den notwendigen Signierungskontext zu protokollieren, beispielsweise:

certificate code
platform
client version
hostname
filename
filesize
sign record id
result

Für:

digest
signature

Bei Daten dieser Größenordnung wird davon abgeraten, sie vollständig in normale Protokolle zu schreiben.

Es können erfasst werden:

Länge.
Hash.
Maskierte Präfix- und Suffix-Anteile.

Der Dateipfad kann ebenfalls Benutzernamen, Projektnamen oder interne Verzeichnisinformationen enthalten; je nach tatsächlichen Sicherheitsanforderungen ist zu entscheiden, ob eine Maskierung erforderlich ist.

Sicherheitshinweise

Bei der API-Integration wird die Befolgung der folgenden Prinzipien empfohlen:

Access Secret sollte nicht im Frontend-Code gespeichert werden.
Access Secret sollte nicht in ein Git-Repository übertragen werden.
Vollständige Authorization-Header sollten nicht in normalen Protokollen aufgezeichnet werden.
Vollständige Access Secrets sollten nicht aufgezeichnet werden.
Führen Sie eine notwendige Protokoll-Maskierung für digest und signature durch.
Remote-Signaturdienste über HTTPS aufrufen.
Der Client sollte HTTP-Status und Geschäftsstatus überprüfen.
Angemessene Timeout- und Wiederholungsstrategien für Netzwerkanfragen festlegen.

Die Remote-Codesignatur-API gibt das Signaturergebnis zurück, nicht den privaten Schlüssel.

Der private Schlüssel für die Codesignatur verbleibt stets im Remote-HSM.

Wann die API verwendet werden sollte

Wenn bestehende Integrationsmethoden die Anforderungen bereits erfüllen, kann in der Regel das entsprechende Werkzeug direkt verwendet werden.

Szenario	Empfohlene Methode
Direkte Signatur von Dateien wie EXE, DLL, MSI	Client-Werkzeug
Windows-Software wie Microsoft SignTool, Visual Studio	Windows Provider
JAR-Dateisignatur	Java-Integration
Automatisierte Builds wie GitHub Actions, Electron Builder	CI/CD- und Build-Werkzeuge
Eigenentwicklung eines Signatur-Clients	API
Eigenständige Implementierung des Dateiformat-Signaturprozesses	API
Direkte Steuerung von Digest und Signaturergebnis erforderlich	API

Die API eignet sich eher für Entwickler, die den zugrunde liegenden Signaturprozess steuern müssen.

Wenn nur gewöhnliche Dateien Codesigniert werden müssen, reduziert die bevorzugte Verwendung bestehender Clients oder Standard-Provider den Aufwand für die eigene Verarbeitung von Signaturdateiformaten.

Zugangsadresse​

Identitätsauthentifizierung​

Allgemeines Anfrageformat​

Allgemeines Antwortformat​

Signaturschnittstelle​

Anfrageparameter​

Zusammenfassungsalgorithmus​

digest-Format​

Padding​

extra​

Beispiel für eine Signieranfrage​

Signaturantwort​

Client-Verarbeitungsablauf​

Signaturergebnis melden​

Anforderungsparameter​

Anfragebeispiel​

Erfolgreiche Antwort​

Signaturanzahl​

Fehlerbehandlung​

Fehler bei der Authentifizierung​

Parameterfehler​

Timeout und Wiederholung​

Protokollierung und Prüfung​

Sicherheitshinweise​

Wann die API verwendet werden sollte​

Zugangsadresse

Identitätsauthentifizierung

Allgemeines Anfrageformat

Allgemeines Antwortformat

Signaturschnittstelle

Anfrageparameter

Zusammenfassungsalgorithmus

digest-Format

Padding

extra

Beispiel für eine Signieranfrage

Signaturantwort

Client-Verarbeitungsablauf

Signaturergebnis melden

Anforderungsparameter

Anfragebeispiel

Erfolgreiche Antwort

Signaturanzahl

Fehlerbehandlung

Fehler bei der Authentifizierung

Parameterfehler

Timeout und Wiederholung

Protokollierung und Prüfung

Sicherheitshinweise

Wann die API verwendet werden sollte