API 整合

sslTrus 提供遠端程式碼簽章 API，適用於需要自行開發簽章用戶端、建置系統或其他簽章整合程式的開發者。

API 接收用戶端計算所得的檔案摘要，由遠端程式碼簽章服務使用指定程式碼簽章憑證完成私鑰簽章，並回傳簽章結果。

用戶端負責：

計算待簽章資料的摘要。
建構目標檔案所需的簽章結構。
呼叫遠端簽章介面。
將回傳的簽章結果寫入目標檔案或簽章結構。
依需求回報用戶端最終處理結果。

程式碼簽章私鑰始終保存在雲端 HSM 中，不會透過 API 回傳給用戶端。

介接位址

生產環境預設位址：

https://ssl.face.racent.com

NICSRS 環境：

https://ssl.face.nicsrs.com

完整簽名接口：

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

結果上報介面：

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

如果實際交付環境使用其他服務地址，請以交付或維運提供的地址為準。

身分認證

API 使用 HTTP Basic Auth。

對應關係：

Username = Access Key
Password = Access Secret

請求標頭：

Authorization: Basic <base64(accessKey:accessSecret)>

例如：

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

實際使用 curl 時，可以直接透過 -u 參數提供：

curl -u "$ACCESS_KEY:$ACCESS_SECRET"

Access Secret 屬於敏感憑證，不應寫入原始碼、公開設定檔、日誌或前端頁面。

通用請求格式

API 使用：

HTTPS
POST
JSON

請求頭：

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

通用響應格式

API 返回統一的 JSON 結構：

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

字段說明：

欄位	類型	說明
`code`	integer	業務狀態碼，`0` 表示成功
`message`	string	狀態或錯誤訊息
`data`	object	介面業務資料

用戶端需要同時判斷 HTTP 狀態碼和業務狀態碼。

建議依照下列方式處理：

HTTP 非 2xx
    ↓
HTTP 请求失败

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

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

不要只根據 HTTP 200 判斷簽名請求成功。

簽名接口

接口：

POST /v1/codesign/sign

該介面用於提交待簽章摘要，並取得遠端私鑰簽章結果。

請求參數

請求範例：

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

主要參數：

參數	類型	必填	說明
`code`	string	是	程式碼簽署證書編號
`digest`	string	是	待簽章摘要原始位元組的 Base64 編碼
`algorithm`	string	是	摘要演算法
`padding`	string	是	RSA 填充方式，目前固定為 `PKCS1`
`extra`	object	否	用戶端上下文和稽核資訊

摘要演算法

目前支援：

SHA1
SHA256

例如使用 SHA-256 時：

{
  "algorithm": "SHA256"
}

algorithm 必須與 digest 實際使用的摘要演算法保持一致。

digest 格式

digest 必須是：

哈希原始位元組 → Base64

不是：

文件内容 Base64

也不是：

十六进制哈希字符串

例如某個 SHA-256 摘要本身為 32 位元組，則應該對這 32 個原始位元組進行 Base64 編碼後傳入介面。

padding

目前固定使用：

PKCS1

即：

{
  "padding": "PKCS1"
}

不要傳入其他填充方式。

extra

extra 用於記錄客戶端上下文、稽核資訊以及輔助問題排查。

支援：

欄位	型別	說明
`platform`	string	用戶端平台
`version`	string	用戶端版本
`revision`	string	用戶端建置 revision
`time`	string	建置時間或請求側記錄時間
`hostname`	string	發起請求的主機名稱
`signing_filename`	string	被簽章檔案名稱或本機路徑
`signing_filesize`	integer	檔案大小，單位為位元組

例如：

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

如果 signing_filename 包含內部目錄、使用者名稱或其他敏感資訊，建議根據客戶端安全策略進行去識別化處理。

簽名請求範例

使用 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

簽名回應

成功回應：

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

返回欄位：

欄位	類型	說明
`id`	string	簽名記錄 ID
`signature`	string	RSA 簽名結果的 Base64 編碼

對於實際簽名能力，用戶端主要使用：

data.signature

如果需要在本地处理完成后上报最终状态，则还需要保存：

data.id

用戶端處理流程

典型流程：

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

需要注意：

/v1/codesign/sign

僅負責底層遠端私鑰簽名。

PE Authenticode、JAR、PDF 或其他檔案格式如何組織簽名結構，由用戶端根據目標格式自行處理。

上報簽名結果

介面：

POST /v1/codesign/report-sign

客戶端收到遠端簽名結果後，仍可能在後續過程中發生失敗，例如：

構造最終簽名結構失敗。
寫入目標檔案失敗。
本機檔案權限錯誤。
後續客戶端處理異常。

可以使用該介面將最終處理狀態回傳給服務端。

請求參數

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

參數：

欄位	類型	必填	說明
`id`	string	是	`/v1/codesign/sign` 返回的簽名記錄 ID
`status`	integer	是	用戶端最終處理狀態

狀態值：

狀態	說明
`1`	用戶端最終處理成功
`2`	用戶端最終處理失敗

請求範例

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

成功響應

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

簽名次數

API 簽名次數以遠程簽名操作是否成功為準。

當：

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

同時成立時，視為一次成功簽名：

签名次数 +1

以下情況不消耗簽名次數：

鑑權失敗。
參數錯誤。
網路請求失敗。
業務請求失敗。
服務端沒有成功返回簽名內容。

需要特別注意：

/v1/codesign/report-sign

只係上報客戶端最終處理狀態，唔屬於新嘅簽名操作，亦唔會增加或減少簽名次數。

即使客戶端已經成功取得遠端簽名結果，但隨後喺本地寫入檔案時失敗，之前成功完成嘅遠端私鑰簽名仍然已經產生一次簽名次數。

更多計次規則請參閱參考資料。

錯誤處理

客戶端應分別處理：

網絡錯誤。
HTTP 錯誤。
API 業務錯誤。
客戶端本地處理錯誤。

鑒權失敗

例如：

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

應檢查：

Access Key 是否正確。
Access Secret 是否正確。
請求是否正確攜帶 Authorization Header。

參數錯誤

例如：

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

應重點檢查：

code 是否正確。
digest 是否為正確的 Base64。
algorithm 與摘要是否一致。
padding 是否為 PKCS1。

用戶端不應依賴固定的：

message

字串執行程序邏輯。

業務處理應優先依據狀態碼和介面契約。

逾時與重試

呼叫遠端簽章介面時，應設定合理的網路逾時。

需要重試時，應特別注意：

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

如果客戶端因為網路異常沒有收到回應，並不代表伺服端一定沒有完成簽名。

因此，在設計自動重試機制時，應避免無限制或無條件重複發起簽名請求。

建議分別記錄：

請求開始時間。
目標憑證編號。
摘要識別碼。
HTTP 狀態。
業務狀態碼。
回傳簽名記錄 ID。
客戶端最終處理狀態。

不要在日誌中記錄完整的 Access Secret。

日誌與稽核

建議記錄必要的簽名上下文，例如：

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

對於：

digest
signature

這類長度較大的資料，不建議完整寫入一般日誌。

可以記錄：

長度。
雜湊。
脫敏後的前後綴。

檔案路徑也可能包含使用者名稱、專案名稱或內部目錄資訊，應依實際安全要求決定是否脫敏。

安全說明

API 整合時建議遵循以下原則：

Access Secret 不應儲存到前端程式碼。
不應將 Access Secret 提交到 Git 儲存庫。
不要在一般日誌中記錄完整 Authorization Header。
不要記錄完整 Access Secret。
對 digest 和 signature 進行必要的日誌脫敏。
透過 HTTPS 呼叫遠端簽名服務。
用戶端應驗證 HTTP 狀態和業務狀態。
為網路請求設定合理的逾時和重試策略。

遠端程式碼簽名 API 回傳的是簽名結果，而不是私鑰。

程式碼簽名私鑰始終保留在遠端 HSM 中。

何時使用 API

如果現有整合方式已能滿足需求，通常可以直接使用對應工具。

場景	推薦方式
直接簽名 EXE、DLL、MSI 等檔案	用戶端工具
Microsoft SignTool、Visual Studio 等 Windows 軟體	Windows Provider
JAR 檔案簽名	Java 整合
GitHub Actions、Electron Builder 等自動建置	CI/CD 與建置工具
自行開發簽名用戶端	API
自行實作檔案格式簽名流程	API
需要直接控制摘要和簽名結果	API

API 更適合需要控制底層簽名流程的開發者。

如果只是需要對一般檔案完成程式碼簽名，優先使用既有用戶端或標準 Provider，可減少自行處理簽名檔案格式的工作量。

介接位址​

身分認證​

通用請求格式​

通用響應格式​

簽名接口​

請求參數​

摘要演算法​

digest 格式​

padding​

extra​

簽名請求範例​

簽名回應​

用戶端處理流程​

上報簽名結果​

請求參數​

請求範例​

成功響應​

簽名次數​

錯誤處理​

鑒權失敗​

參數錯誤​

逾時與重試​

日誌與稽核​

安全說明​

何時使用 API​

介接位址

身分認證

通用請求格式

通用響應格式

簽名接口

請求參數

摘要演算法

digest 格式

padding

extra

簽名請求範例

簽名回應

用戶端處理流程

上報簽名結果

請求參數

請求範例

成功響應

簽名次數

錯誤處理

鑒權失敗

參數錯誤

逾時與重試

日誌與稽核

安全說明

何時使用 API