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
SHA384
SHA512

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