メインコンテンツまでスキップ

远程代码署名 API 参考

本稿は、リモート署名機能を直接統合する必要がある開発者向けに、以下の2つのインターフェースについて説明します：

  • 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)>

認証​

APIは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クライアントビルドの改訂版。
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 エンコード である必要があり、16進文字列や完全なファイル内容ではありません。
  • algorithm は digest の実際のハッシュアルゴリズムと一致している必要があります。
  • 現在のパディングモードは固定で PKCS1 を使用しており、他の値を渡さないでください。
  • digest および signature フィールドは長くなる可能性があるため、ログには長さのみ、または前後の一部をマスクした結果のみを記録することを推奨します。
  • クライアントで最終処理を完了した後、report-sign を呼び出して結果を報告し、その後の監査や調査を容易にすることを推奨します。
  • ネットワークエラー、HTTP エラー、ビジネスエラーをそれぞれ分けて処理し、署名リクエストには適切なタイムアウトと再試行ポリシーを設定してください。
に最終更新