API-Integration

sslTrus bietet eine Remote-Codesignatur-API für Entwickler an, die eigene Signaturclients, Build-Systeme oder andere Signaturintegrationsprogramme entwickeln müssen.

Die API empfängt den vom Client berechneten Datei-Digest, der Remote-Codesignaturdienst führt die Signatur mit dem privaten Schlüssel des angegebenen Codesignaturzertifikats durch und gibt das Signaturergebnis zurück.

Der Client ist verantwortlich für:

Berechnung des Digests der zu signierenden Daten.
Aufbau der für die Zieldatei erforderlichen Signaturstruktur.
Aufruf der Remote-Signaturschnittstelle.
Schreiben des zurückgegebenen Signaturergebnisses in die Zieldatei oder Signaturstruktur.
Bei Bedarf Meldung des endgültigen Verarbeitungsergebnisses des Clients.

Der private Schlüssel der Codesignatur wird stets im Cloud-HSM gespeichert und wird dem Client nicht über die API zurückgegeben.

Zugangsadresse

Standardadresse der Produktionsumgebung:

https://ssl.face.racent.com

NICSRS-Umgebung:

https://ssl.face.nicsrs.com

Vollständige Signaturschnittstelle:

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

Ergebnismelde-Schnittstelle:

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

Wenn die tatsächliche Bereitstellungsumgebung andere Dienstadressen verwendet, richten Sie sich bitte nach den von der Bereitstellung oder dem Betrieb bereitgestellten Adressen.

Identitätsauthentifizierung

Die API verwendet HTTP Basic Auth.

Entsprechungen:

Username = Access Key
Password = Access Secret

Anforderungsheader:

Authorization: Basic <base64(accessKey:accessSecret)>

例如：

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

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

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret ist eine sensible Zugangsberechtigung und darf nicht in Quellcode, öffentliche Konfigurationsdateien, Logs oder Frontend-Seiten geschrieben werden.

Allgemeines Anfrageformat

Verwendung der API:

HTTPS
POST
JSON

Anforderungsheader:

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äftsstatuscode, `0` bedeutet Erfolg
`message`	string	Status- oder Fehlermeldung
`data`	object	Geschäftsdaten der Schnittstelle

Der Client muss sowohl den HTTP-Statuscode als auch den Geschäftsstatuscode prüfen.

Es wird empfohlen, wie folgt vorzugehen:

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

Beurteilen Sie den Erfolg der Signaturanfrage nicht allein anhand von HTTP 200.

Signaturschnittstelle

Schnittstelle:

POST /v1/codesign/sign

Diese Schnittstelle wird verwendet, um eine zu signierende Digest einzureichen und das Signaturergebnis des entfernten privaten Schlüssels abzurufen.

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

Hauptparameter:

Parameter	Typ	Erforderlich	Beschreibung
`code`	string	Ja	Nummer des Codesignatur-Zertifikats
`digest`	string	Ja	Base64-Kodierung der Rohbytes der zu signierenden Digest
`algorithm`	string	Ja	Digest-Algorithmus
`padding`	string	Ja	RSA-Padding-Verfahren, derzeit fest auf `PKCS1`
`extra`	object	Nein	Client-Kontext und Audit-Informationen

Digest-Algorithmus

Derzeit unterstützt:

SHA1
SHA256
SHA384
SHA512

Z. B. bei Verwendung von SHA-256:

{
  "algorithm": "SHA256"
}

algorithm 必须与 digest 实际使用的摘要算法保持一致。

digest 格式

digest 必须是：

Hash-Rohbytes → Base64

Nein:

文件内容 Base64

auch nicht:

十六进制哈希字符串

Beispiel: Wenn ein SHA-256-Digest selbst 32 Bytes umfasst, sollten diese 32 Rohbytes Base64-codiert und an die Schnittstelle übergeben werden.

padding

Aktuell fest verwendet:

PKCS1

Das heißt:

{
  "padding": "PKCS1"
}

Geben Sie keine anderen Füllmethoden an.

extra

extra wird verwendet, um Client-Kontext, Audit-Informationen sowie zur Unterstützung bei der Problembehebung zu erfassen.

Unterstützt:

Feld	Typ	Beschreibung
`platform`	string	Client-Plattform
`version`	string	Client-Version
`revision`	string	Build-Revision des Clients
`time`	string	Build-Zeit oder auf Anforderungsseite erfasste Zeit
`hostname`	string	Hostname, der die Anforderung initiiert
`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 vertrauliche Informationen enthält, wird empfohlen, diese gemäß den Sicherheitsrichtlinien des Kunden zu maskieren.

Beispiel einer Signaturanforderung

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

Signierte Antwort

Erfolgsantwort:

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

Rückgabefelder:

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

Für die eigentliche Signaturfähigkeit verwendet der Client hauptsächlich:

data.signature

Wenn der endgültige Status nach der lokalen Verarbeitung gemeldet werden muss, muss außerdem Folgendes gespeichert werden:

data.id

Verarbeitungsablauf auf Client-Seite

Typischer Ablauf:

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

Beachten Sie:

/v1/codesign/sign

Nur für die zugrunde liegende entfernte Signatur mit privatem Schlüssel zuständig.

Wie PE Authenticode, JAR, PDF oder andere Dateiformate die Signaturstruktur organisieren, wird vom Client je nach Zielformat eigenständig verarbeitet.

Signaturergebnis melden

Schnittstelle:

POST /v1/codesign/report-sign

Nachdem der Client das Ergebnis der Remote-Signatur erhalten hat, kann es im weiteren Verlauf weiterhin zu Fehlern kommen, zum Beispiel:

Fehler beim Erstellen der endgültigen Signaturstruktur.
Fehler beim Schreiben der Zieldatei.
Falsche Berechtigungen der lokalen Datei.
Spätere Fehler bei der clientseitigen Verarbeitung.

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

Anfrageparameter

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

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

Statuswerte:

Status	Beschreibung
`1`	Endgültige Verarbeitung durch den Client erfolgreich
`2`	Endgültige Verarbeitung durch den Client fehlgeschlagen

Anforderungsbeispiel

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

Erfolgsantwort

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

Anzahl der Signaturen

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

Wenn:

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

Wenn gleichzeitig die folgenden Bedingungen erfüllt sind, gilt dies als eine erfolgreiche Signatur:

签名次数 +1

Die folgenden Fälle verbrauchen keine Signaturkontingente:

Authentifizierungsfehler.
Parameterfehler.
Netzwerkanfragefehler.
Fehlgeschlagene Geschäftsanfrage.
Der Server hat den Signaturinhalt nicht erfolgreich zurückgegeben.

Besonders zu beachten:

/v1/codesign/report-sign

Es wird nur der endgültige Verarbeitungsstatus des Clients gemeldet. Es handelt sich weder um einen neuen Signaturvorgang, noch erhöht oder verringert sich dadurch die Anzahl der Signaturen.

Selbst wenn der Client das Ergebnis der Remote-Signatur erfolgreich erhalten hat, beim anschließenden lokalen Schreiben in die Datei jedoch ein Fehler auftritt, hat die zuvor erfolgreich abgeschlossene Remote-Signatur mit dem privaten Schlüssel bereits eine Signaturzählung erzeugt.

Weitere Regeln zur Zählung finden Sie unter Referenzmaterialien.

Fehlerbehandlung

Der Client sollte jeweils getrennt behandeln:

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

Authentifizierungsfehler

Zum Beispiel:

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

Zu prüfen:

Ist der Access Key korrekt?
Ist das Access Secret korrekt?
Enthält die Anfrage den Authorization-Header korrekt?

Parameterfehler

Beispiel:

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

应重点检查：

code 是否正确。
digest 是否为正确的 Base64。
algorithm 与摘要是否一致。
padding 是否为 PKCS1。

客户端不应依赖固定的：

message

Zeichenfolgen führen die Programmlogik aus.

Die Geschäftsverarbeitung sollte sich vorrangig an Statuscodes und am Schnittstellenvertrag orientieren.

Timeouts und Wiederholungen

Beim Aufruf der Remotesignatur-Schnittstelle sollte ein angemessenes Netzwerk-Timeout festgelegt werden.

Wenn Wiederholungen erforderlich sind, ist besonders zu beachten:

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

Falls der Client aufgrund einer Netzwerkstörung keine Antwort erhält, bedeutet das nicht zwangsläufig, dass der Server die Signatur nicht abgeschlossen hat.

Daher sollte beim Entwurf eines automatischen Wiederholungsmechanismus vermieden werden, Signaturanforderungen unbegrenzt oder bedingungslos erneut zu senden.

Es wird empfohlen, jeweils Folgendes zu protokollieren:

Zeitpunkt des Anforderungsbeginns.
Kennnummer des Zielzertifikats.
Digest-Kennung.
HTTP-Status.
Geschäftsstatuscode.
ID des zurückgegebenen Signaturdatensatzes.
Endgültiger Verarbeitungsstatus des Clients.

Der vollständige Access Secret darf nicht im Protokoll erfasst werden.

Protokollierung und Audit

Es wird empfohlen, den erforderlichen Signaturkontext zu protokollieren, zum Beispiel:

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.

Protokolliert werden können:

Länge.
Hash.
Maskierte Präfixe und Suffixe.

Auch Dateipfade können Benutzernamen, Projektnamen oder interne Verzeichnisinformationen enthalten. Ob sie maskiert werden müssen, sollte anhand der tatsächlichen Sicherheitsanforderungen entschieden werden.

Sicherheitshinweise

Bei der API-Integration werden folgende Grundsätze empfohlen:

Access Secret sollte nicht im Frontend-Code gespeichert werden.
Access Secret sollte nicht in Git-Repositorys eingecheckt werden.
Der vollständige Authorization Header sollte nicht in normale Protokolle geschrieben werden.
Das vollständige Access Secret sollte nicht protokolliert werden.
Führen Sie für digest und signature die erforderliche Protokollmaskierung durch.
Rufen Sie den Remote-Signaturdienst über HTTPS auf.
Der Client sollte HTTP-Status und Geschäftsstatus prüfen.
Legen Sie angemessene Timeout- und Wiederholungsrichtlinien für Netzwerkanfragen fest.

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

Der private Codesignaturschlüssel verbleibt stets im Remote-HSM.

Wann die API verwendet werden sollte

Wenn bestehende Integrationsmethoden die Anforderungen bereits erfüllen, können in der Regel direkt die entsprechenden Tools verwendet werden.

Szenario	Empfohlene Methode
Direktes Signieren von EXE-, DLL-, MSI- und anderen Dateien	Client-Tool
Microsoft SignTool, Visual Studio und andere Windows-Software	Windows Provider
Signieren von JAR-Dateien	Java-Integration
GitHub Actions, Electron Builder und andere automatisierte Builds	CI/CD und Build-Tools
Eigene Entwicklung eines Signaturclients	API
Eigene Implementierung des Signaturablaufs für Dateiformate	API
Direkte Kontrolle über Digest und Signaturergebnis erforderlich	API

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

Wenn lediglich gewöhnliche Dateien codesigniert werden müssen, reduziert die vorrangige Nutzung vorhandener Clients oder Standard-Provider den Aufwand für die eigene Verarbeitung signierter Dateiformate.

Zugangsadresse​

Identitätsauthentifizierung​

Allgemeines Anfrageformat​

Allgemeines Antwortformat​

Signaturschnittstelle​

Anfrageparameter​

Digest-Algorithmus​

digest 格式​

padding​

extra​

Beispiel einer Signaturanforderung​

Signierte Antwort​

Verarbeitungsablauf auf Client-Seite​

Signaturergebnis melden​

Anfrageparameter​

Anforderungsbeispiel​

Erfolgsantwort​

Anzahl der Signaturen​

Fehlerbehandlung​

Authentifizierungsfehler​

Parameterfehler​

Timeouts und Wiederholungen​

Protokollierung und Audit​

Sicherheitshinweise​

Wann die API verwendet werden sollte​

Zugangsadresse

Identitätsauthentifizierung

Allgemeines Anfrageformat

Allgemeines Antwortformat

Signaturschnittstelle

Anfrageparameter

Digest-Algorithmus

digest 格式

padding

extra

Beispiel einer Signaturanforderung

Signierte Antwort

Verarbeitungsablauf auf Client-Seite

Signaturergebnis melden

Anfrageparameter

Anforderungsbeispiel

Erfolgsantwort

Anzahl der Signaturen

Fehlerbehandlung

Authentifizierungsfehler

Parameterfehler

Timeouts und Wiederholungen

Protokollierung und Audit

Sicherheitshinweise

Wann die API verwendet werden sollte