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"

アクセスシークレットは機密資格情報であり、ソースコード、公開設定ファイル、ログ、またはフロントエンドページに書き込むべきではありません。

一般的なリクエスト形式

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 を使用する場面