跳至主要内容

遠端程式碼簽章 API 參考

本文面向需要直接整合遠端簽章能力的開發者，說明以下兩個介面：

  • POST /v1/codesign/sign：提交待簽章雜湊摘要，取得 RSA PKCS#1 簽章結果。
  • POST /v1/codesign/report-sign：上報用戶端最終處理結果（不影響簽章計次）。

接入位址​

環境位址
正式環境（預設）https://ssl.face.racent.com
NICSRS 環境https://ssl.face.nicsrs.com

如需其他環境位址，以交付或維運提供的位址為準。

通用約定​

請求格式​

  • 協定：HTTPS
  • Method：POST
  • Body：JSON
  • Headers：
Content-Type: application/json
Accept: application/json
Authorization: Basic <base64(accessKey:accessSecret)>

鑑權​

介面使用 HTTP Basic Auth：

  • Username：Access Key
  • Password：Access Secret

生成 Authorization 標頭：

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

通用回應結構​

{
  "code": 0,
  "message": "ok",
  "data": {}
}
字段類型含義
codeinteger業務狀態碼。0 表示成功，非 0 表示業務失敗。
messagestring業務狀態說明，失敗時為錯誤描述。
dataobject介面業務資料。

呼叫方應同時處理 HTTP 狀態碼和業務狀態碼：

  • HTTP 非 2xx → 按 HTTP 錯誤處理。
  • HTTP 2xx 且 code != 0 → 按業務錯誤處理。
  • HTTP 2xx 且 code == 0 → 讀取對應的 data。

簽章介面​

介面說明​

POST /v1/codesign/sign

提交待簽名雜湊原始位元組（Base64 編碼），由遠端服務使用指定憑證完成 RSA PKCS#1 簽章並傳回結果。

注意

/v1/codesign/sign 成功傳回簽章內容即視為簽章成功，簽章次數加 1。失敗請求不會消耗簽章次數。是否呼叫 report-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
  }
}
欄位類型必填含義
codestring是證書編號，用於選擇遠端簽章憑證。
digeststring是待簽章雜湊原始位元組的 Base64 編碼。呼叫方需依目標檔案與簽章工具要求在本機計算雜湊。
algorithmstring是雜湊演算法，支援 SHA1、SHA256、SHA384、SHA512。
paddingstring是RSA 填充模式，當前固定為 PKCS1。
extraobject否用戶端上下文資訊，用於簽章記錄、稽核與問題排查。

extra 欄位說明：

欄位類型含義
platformstring用戶端平台，例如 windows/amd64、linux/amd64。
versionstring用戶端版本。
revisionstring客戶端建置 revision。
timestring客戶端建置時間或請求時間。
hostnamestring發起簽名的主機名稱。
signing_filenamestring被簽名檔案名稱或路徑，建議依安全策略脫敏。
signing_filesizeinteger被簽名檔案大小（位元組）。

請求範例​

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

成功回應​

{
  "code": 0,
  "message": "ok",
  "data": {
    "id": "735985894427246592",
    "signature": "BASE64_ENCODED_SIGNATURE"
  }
}
欄位類型含義
idstring簽名記錄 ID，呼叫 report-sign 時使用。
signaturestringRSA 簽名結果的 Base64 編碼。

上報簽名結果​

介面說明​

POST /v1/codesign/report-sign

客戶端在取得遠端簽章結果後，可能於本機處理、寫入或交還呼叫方時失敗。此介面用於將客戶端最終處理狀態回傳至服務端，以便簽章記錄展示與稽核排查。

說明

此介面僅記錄客戶端處理結果，不會改變 /v1/codesign/sign 的計次結果。不呼叫此介面不影響簽章成功次數。

請求參數​

{
  "id": "735985894427246592",
  "status": 1
}
欄位類型必填含義
idstring是/v1/codesign/sign 回傳的 data.id。
statusinteger是用戶端最終處理狀態：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
}

錯誤回應範例​

鑑權失敗：

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

參數錯誤：

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

具體錯誤碼和錯誤訊息以服務端實際回傳為準。接入方不應依賴固定錯誤文案做業務分支判斷。

接入建議​

  • 妥善保護 Access Secret，不要寫入日誌、當機報告或前端頁面。
  • digest 必須是雜湊原始位元組的 Base64 編碼，不是十六進位字串，也不是完整檔案內容。
  • algorithm 必須與 digest 的實際雜湊演算法一致。
  • 當前填充模式固定使用 PKCS1，不要傳入其他值。
  • digest 和 signature 欄位可能較長，日誌中建議只記錄長度或前後綴遮罩結果。
  • 建議在用戶端完成最終處理後呼叫 report-sign 上報結果，便於後續稽核排查。
  • 對網路錯誤、HTTP 錯誤和業務錯誤分別處理，並為簽章請求設定合理的逾時和重試策略。
最後於 更新