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

リモートコード署名 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
  • メソッド：POST
  • Body：JSON
  • ヘッダー：
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エンコード である必要があり、16進文字列でも完全なファイル内容でもありません。
  • algorithm は digest の実際のハッシュアルゴリズムと一致している必要があります。
  • 現在、パディングモードは固定で PKCS1 を使用します。他の値を渡さないでください。
  • digest および signature フィールドは長くなる場合があるため、ログには長さのみを記録するか、接頭辞・接尾辞をマスクした結果を記録することを推奨します。
  • クライアント側で最終処理が完了した後、report-sign を呼び出して結果をアップロードすることを推奨します。これにより、後続の監査およびトラブルシューティングが容易になります。
  • ネットワークエラー、HTTPエラー、業務エラーをそれぞれ個別に処理し、署名リクエストには適切なタイムアウトとリトライポリシーを設定してください。
に最終更新